daytona 0.227.0 → 0.227.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5d32a60cce6fb9e9e9c4bed6bab5bd2ca0e801870be6416e3532b52ef3eccc1
-  data.tar.gz: 2dfa28c4f72d59d0e07b3e1379b38d42b0552e7718880f84be32eaa35285b6b3
+  metadata.gz: 1fe1f1b23586f2b803d7c8b808a8696d5148308c4dca36a02431b951f0a0be42
+  data.tar.gz: 7707f83ac63438f031beb4b68d0497bdbd20799dba7109bc047bbc3f56ceb116
 SHA512:
-  metadata.gz: 2769f764e2980e8ec34f4e171967445464313157f2ee45627083717796a1d9010a25ed84d26d0e6f62b89d07dff869fd8940616125335672b544f73635ba4b2a
-  data.tar.gz: 2f6219d2cdeeea6997d78c8ae38ca760eff8e5a7f54ef2ec16c9fe70295b966197df5783e185c7af32c8c9f64a1b3cb71864c99538a3c90579b93dbda53eb6d6
+  metadata.gz: 35c3979e512ef9d4d3657380ef20019678754849418c68b0fe1c40fcb97ad33116322c5c2fcac52a11b050d19a7e4555fb89c8b940d41459c01a8949692f0533
+  data.tar.gz: 4d0c59583e76f02d327c91c61c06f1e6f3941a97346fc92ebc6295f905005d045d1324c57c40932b6f311c140ad1cca2b134dbd87abfbe5c5c0991affd9909dc

data/README.md

@@ -120,6 +120,43 @@ sandbox = daytona.create(
 )
 ```
 
+### Handle sandbox creation timeouts
+
+There are two timeouts:
+
+- `queue_timeout` (minutes, in the params): if no runner takes the sandbox in time, the API deletes it and `create` raises `Daytona::Sdk::QueueTimeoutError`.
+- `timeout` (seconds, 60 by default, `0` for no limit): if the sandbox hasn't started in time, `create` raises `Daytona::Sdk::TimeoutError`. The sandbox may still be starting, so delete it yourself using `sandbox_id` from the error.
+  If the create request itself timed out, `sandbox_id` is `nil`, but the API may still have created the sandbox, and it can take a few seconds to show up. Give your sandboxes labels so you can find and delete these later with `list`.
+
+```ruby
+require 'daytona'
+require 'securerandom'
+
+daytona = Daytona::Daytona.new
+labels = { 'job' => SecureRandom.uuid }
+begin
+  sandbox = daytona.create(
+    Daytona::CreateSandboxFromImageParams.new(image: Daytona::Image.debian_slim('3.12'), queue_timeout: 5, labels:),
+    timeout: 300
+  )
+rescue Daytona::Sdk::TimeoutError => e
+  if e.sandbox_id
+    begin
+      daytona.delete(daytona.get(e.sandbox_id))
+    rescue Daytona::Sdk::NotFoundError
+      # Already gone, nothing to clean up
+    end
+  end
+  raise e
+end
+```
+
+A few seconds later (e.g. at the end of the job, or from a cleanup job that kept the labels), delete what a timed out create request may have left behind:
+
+```ruby
+daytona.list(Daytona::ListSandboxesQuery.new(labels:)).each { |s| daytona.delete(s) }
+```
+
 ### Execute commands
 
 Execute commands in the sandbox.

data/lib/daytona/daytona.rb

@@ -102,10 +102,21 @@ module Daytona
     # Creates a sandbox with the specified parameters
     #
     # @param params [Daytona::CreateSandboxFromSnapshotParams, Daytona::CreateSandboxFromImageParams, Nil] Sandbox creation parameters
+    # @param timeout [Numeric] Maximum time in seconds to wait for the Sandbox to be created and started
+    #   (defaults to 60 s). Sandbox::NO_TIMEOUT (0) means no timeout.
+    # @param on_snapshot_create_logs [Proc]
     # @return [Daytona::Sandbox] The created sandbox
-    # @raise [Daytona::Sdk::Error] If auto_stop_interval, auto_pause_interval, auto_archive_interval, or ttl_minutes is negative,
-    #   if queue_timeout is not a positive integer, or if auto_stop_interval and auto_pause_interval are both non-zero
-    def create(params = nil, on_snapshot_create_logs: nil)
+    # @raise [Daytona::Sdk::Error] If timeout, auto_stop_interval, auto_pause_interval, auto_archive_interval,
+    #   or ttl_minutes is negative, if queue_timeout is not a positive integer, or if auto_stop_interval and
+    #   auto_pause_interval are both non-zero
+    # @raise [Daytona::Sdk::TimeoutError] If the Sandbox is not started within timeout. When the Sandbox was
+    #   already created, the error's sandbox_id names it: it may still be starting, so fetch it with #get
+    #   and remove it with #delete. When the create request itself timed out, sandbox_id is nil, but the API
+    #   may still have created the Sandbox: find it by its labels with #list (it can take a few seconds to show up)
+    # @raise [Daytona::Sdk::QueueTimeoutError] If the API destroyed the Sandbox because it waited longer than
+    #   queue_timeout for a runner
+    # @raise [Daytona::Sdk::SpotEvictedError] If the Sandbox was destroyed by spot preemption while starting
+    def create(params = nil, timeout: Sandbox::DEFAULT_TIMEOUT, on_snapshot_create_logs: nil)
       if params.nil?
         params = CreateSandboxFromSnapshotParams.new(language: CodeLanguage::PYTHON)
       elsif params.language.nil?
@@ -117,7 +128,7 @@ module Daytona
               "Invalid #{CODE_TOOLBOX_LANGUAGE_LABEL}: #{params.language}. Supported languages: #{CodeLanguage::ALL.join(', ')}"
       end
 
-      _create(params, on_snapshot_create_logs:)
+      _create(params, timeout:, on_snapshot_create_logs:)
     end
 
     # Deletes a Sandbox.
@@ -245,15 +256,15 @@ module Daytona
     # Creates a sandbox with the specified parameters
     #
     # @param params [Daytona::CreateSandboxFromSnapshotParams, Daytona::CreateSandboxFromImageParams] Sandbox creation parameters
-    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @param timeout [Numeric] Maximum wait time in seconds. Sandbox::NO_TIMEOUT (0) means no timeout.
     # @param on_snapshot_create_logs [Proc]
     # @return [Daytona::Sandbox] The created sandbox
-    # @raise [Daytona::Sdk::Error] If auto_stop_interval, auto_pause_interval, auto_archive_interval, or ttl_minutes is negative,
+    # @raise [Daytona::Sdk::Error] If timeout, auto_stop_interval, auto_pause_interval, auto_archive_interval, or ttl_minutes is negative,
     #   if queue_timeout is not a positive integer, or if auto_stop_interval and auto_pause_interval are both non-zero
-    def _create(params, timeout: 60, on_snapshot_create_logs: nil)
+    def _create(params, timeout:, on_snapshot_create_logs: nil)
       raise Sdk::Error, 'Timeout must be a non-negative number' if timeout.negative?
 
-      start_time = Time.now
+      start_time = monotonic_now
 
       raise Sdk::Error, 'auto_stop_interval must be a non-negative integer' if params.auto_stop_interval&.negative?
 
@@ -329,17 +340,19 @@ module Daytona
         end
       end
 
-      response = sandbox_api.create_sandbox(create_sandbox)
+      response = request_sandbox_creation(create_sandbox, timeout, start_time)
+      sandbox_id = response.id
 
       if response.state == DaytonaApiClient::SandboxState::PENDING_BUILD && on_snapshot_create_logs
         # Wait for state to change from PENDING_BUILD before fetching logs
         while response.state == DaytonaApiClient::SandboxState::PENDING_BUILD
+          raise_if_timed_out(timeout, start_time)
           sleep(1)
-          response = sandbox_api.get_sandbox(response.id)
+          response = sandbox_api.get_sandbox(sandbox_id)
         end
 
         begin
-          build_logs_response = sandbox_api.get_build_logs_url(response.id)
+          build_logs_response = sandbox_api.get_build_logs_url(sandbox_id)
           uri = URI.parse("#{build_logs_response.url}?follow=true")
 
           headers = {}
@@ -347,7 +360,7 @@ module Daytona
           Util.stream_async(uri:, headers:, on_chunk: on_snapshot_create_logs)
         rescue StandardError => e
           refreshed = begin
-            sandbox_api.get_sandbox(response.id)
+            sandbox_api.get_sandbox(sandbox_id)
           rescue StandardError
             raise e
           end
@@ -360,12 +373,14 @@ module Daytona
       sandbox = to_sandbox(sandbox_dto: response)
 
       if sandbox.state != DaytonaApiClient::SandboxState::STARTED
-        sandbox.wait_for_sandbox_start([0.001, timeout - (Time.now - start_time)].max)
+        sandbox.wait_for_sandbox_start(remaining_timeout(timeout, start_time))
       end
 
       sandbox
     rescue *Sdk::API_ERROR_CLASSES => e
-      raise Sdk.wrap_error(e, 'Failed to create sandbox')
+      raise name_created_sandbox(Sdk.wrap_error(e, 'Failed to create sandbox'), sandbox_id, timeout)
+    rescue Sdk::TimeoutError => e
+      raise name_created_sandbox(e, sandbox_id, timeout)
     end
 
     # @return [void]
@@ -419,6 +434,79 @@ module Daytona
       end
     end
 
+    # @param timeout [Numeric]
+    # @param start_time [Float] Reading of #monotonic_now
+    # @return [Numeric] What is left of timeout since start_time, at least 1 ms; Sandbox::NO_TIMEOUT stays as is
+    def remaining_timeout(timeout, start_time)
+      return Sandbox::NO_TIMEOUT if timeout.zero?
+
+      [0.001, timeout - (monotonic_now - start_time)].max
+    end
+
+    # @param timeout [Numeric]
+    # @param start_time [Float] Reading of #monotonic_now
+    # @return [void]
+    # @raise [Daytona::Sdk::TimeoutError] If timeout has run out since start_time
+    def raise_if_timed_out(timeout, start_time)
+      return if timeout.zero? || monotonic_now - start_time < timeout
+
+      raise Sdk::TimeoutError, "Sandbox build has been pending for more than #{timeout} seconds"
+    end
+
+    # Sends the create request with what is left of timeout as its HTTP timeout.
+    #
+    # @param create_sandbox [DaytonaApiClient::CreateSandbox]
+    # @param timeout [Numeric]
+    # @param start_time [Float] Reading of #monotonic_now
+    # @return [DaytonaApiClient::Sandbox]
+    # @raise [Daytona::Sdk::TimeoutError] If timeout runs out before or during the request
+    def request_sandbox_creation(create_sandbox, timeout, start_time)
+      message = "Failed to create and start sandbox within #{timeout} seconds. Operation timed out."
+      # Once timeout has run out (e.g. while uploading the build context), don't create a Sandbox
+      # that the TimeoutError could not name.
+      raise Sdk::TimeoutError, message unless timeout.zero? || monotonic_now - start_time < timeout
+
+      client = api_client_with_timeout(remaining_timeout(timeout, start_time))
+      DaytonaApiClient::SandboxApi.new(client).create_sandbox(create_sandbox)
+    rescue DaytonaApiClient::ApiError => e
+      # The generated client raises this, without a status code, when the request times out.
+      raise unless e.code.nil? && e.message == 'Connection timed out'
+
+      raise Sdk::TimeoutError, message
+    end
+
+    # The generated client takes a timeout only from its configuration, so this copies api_client with a
+    # configuration that differs only in the timeout. Headers and settings changed on api_client still apply.
+    #
+    # @param timeout [Numeric] HTTP timeout in seconds. Sandbox::NO_TIMEOUT (0) means no timeout.
+    # @return [DaytonaApiClient::ApiClient]
+    def api_client_with_timeout(timeout)
+      api_client.dup.tap { |client| client.config = api_client.config.dup.tap { |c| c.timeout = timeout } }
+    end
+
+    # @return [Float] Seconds on a clock that wall clock changes don't move, for measuring timeouts
+    def monotonic_now
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+
+    # @param error [Daytona::Sdk::Error]
+    # @param sandbox_id [String, nil] Id of the created Sandbox, nil if creation failed
+    # @param timeout [Numeric]
+    # @return [Daytona::Sdk::Error] error as is, or a TimeoutError naming the Sandbox if it had been created
+    def name_created_sandbox(error, sandbox_id, timeout)
+      return error if sandbox_id.nil? || !error.is_a?(Sdk::TimeoutError) || error.is_a?(Sdk::QueueTimeoutError)
+
+      named = Sdk::TimeoutError.new(
+        "Failed to create and start sandbox within #{timeout} seconds. Operation timed out. " \
+        "Sandbox #{sandbox_id} was created before the timeout and may still be starting. " \
+        "Use daytona.get('#{sandbox_id}') to check on it, and pass the returned Sandbox to daytona.delete() " \
+        'to remove it.',
+        status_code: error.status_code, code: error.code, source: error.source, headers: error.headers
+      )
+      named.sandbox_id = sandbox_id
+      named
+    end
+
     def to_sandbox(sandbox_dto:)
       Sandbox.new(
         sandbox_dto:,

data/lib/daytona/sandbox.rb

@@ -18,6 +18,10 @@ module Daytona
     include Instrumentation
 
     DEFAULT_TIMEOUT = 60
+
+    # Pass as a timeout to wait without a limit.
+    NO_TIMEOUT = 0
+
     def self.with_events(*method_names)
       method_names.each do |method_name|
         original = instance_method(method_name)
@@ -1425,9 +1429,6 @@ module Daytona
     POLL_BACKOFF_DELAY = 5.0
     private_constant :POLL_BACKOFF_DELAY
 
-    NO_TIMEOUT = 0
-    private_constant :NO_TIMEOUT
-
     def wait_for_snapshot_complete
       error_states = [DaytonaApiClient::SandboxState::ERROR, DaytonaApiClient::SandboxState::BUILD_FAILED]
       exclude = [DaytonaApiClient::SandboxState::SNAPSHOTTING] + error_states

data/lib/daytona/sdk/errors.rb

@@ -74,7 +74,11 @@ module Daytona
     class NotFoundError < Error; end
 
     # HTTP 408 / 504 / client-side timeouts.
-    class TimeoutError < Error; end
+    class TimeoutError < Error
+      # @return [String, nil] Set only on the TimeoutError from Daytona#create after the Sandbox was created:
+      #   it may still be starting, so delete it. Nil on every other timeout.
+      attr_accessor :sandbox_id
+    end
 
     # HTTP 409 — request conflicts with current resource state.
     class ConflictError < Error; end
@@ -112,7 +116,8 @@ module Daytona
     # ---------------------------------------------------------------------
 
     # Raised when a Sandbox was destroyed by the API because it waited longer
-    # than its queue timeout for a runner.
+    # than its queue timeout for a runner. Leaves sandbox_id unset, as there
+    # is no Sandbox left to clean up.
     class QueueTimeoutError < TimeoutError; end
 
     # Raised when a Sandbox was destroyed by spot preemption.

data/lib/daytona/sdk/version.rb

@@ -5,6 +5,6 @@
 
 module Daytona
   module Sdk
-    VERSION = '0.227.0'
+    VERSION = '0.227.3'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: daytona
 version: !ruby/object:Gem::Version
-  version: 0.227.0
+  version: 0.227.3
 platform: ruby
 authors:
 - Daytona Platforms Inc.
@@ -91,42 +91,42 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.227.0
+        version: 0.227.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.227.0
+        version: 0.227.3
 - !ruby/object:Gem::Dependency
   name: daytona_api_client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.227.0
+        version: 0.227.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.227.0
+        version: 0.227.3
 - !ruby/object:Gem::Dependency
   name: daytona_toolbox_api_client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.227.0
+        version: 0.227.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.227.0
+        version: 0.227.3
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement