pinesandbox 0.3.18 → 0.3.19

data/lib/pinesandbox/client.rb

@@ -176,7 +176,7 @@ module PineSandbox
       provider.available_locations
     end
 
-    # Optional configuration discovery, not a runtime operation prerequisite.
+    # Optional configuration discovery, not a lifecycle operation prerequisite.
     def project_policy
       provider = @connection.attach_provider
       raise ArgumentError, "project policy requires a project API key provider" unless provider.respond_to?(:project_policy)
@@ -253,8 +253,8 @@ module PineSandbox
       location ? provider.register_computer(computer_id, location: location) : provider.register_computer(computer_id)
     end
 
-    # Re-attach an EXISTING persistent Computer by its stored id + state key. A fresh
-    # runtime is allocated and bound with the Computer's prior state restored.
+    # Re-attach an EXISTING persistent Computer by its stored id + state key. The
+    # Computer starts and is bound with its prior state restored.
     # The id may be given positionally or as `id:` (matching #create_computer).
     def start_computer(*args, **options)
       if args.first.is_a?(Computer::Credentials)
@@ -264,11 +264,11 @@ module PineSandbox
         credentials, *args = args
         options = credentials_options(credentials, options)
       end
-      start_existing_computer(*args, **options, recover_runtime: false)
+      start_existing_computer(*args, **options, recover: false)
     end
 
     # Gracefully stop the binding observed for this ID, even when a caller lost
-    # its Start response before saving the runtime token. Never follow a newer
+    # its Start response before saving the Computer token. Never follow a newer
     # binding during this invocation; project authorization is sufficient.
     def stop_computer(computer_id, **wait_options)
       raise ArgumentError, "id must be a lowercase UUIDv7" unless computer_id.to_s.match?(Computer::UUID_V7)
@@ -277,27 +277,27 @@ module PineSandbox
         raise ArgumentError, "Stop by ID requires a provider with current_binding"
       end
       reference = provider.current_binding(computer_id)
-      runtime_id = reference["sandbox_id"]
-      return true if runtime_id.nil?
+      sandbox_id = reference["sandbox_id"]
+      return true if sandbox_id.nil?
 
-      RuntimeHandle.new(control_plane: @connection.control_plane, runtime_id: runtime_id).stop(**wait_options)
+      SandboxHandle.new(control_plane: @connection.control_plane, sandbox_id: sandbox_id).stop(**wait_options)
     rescue UnknownComputerError
       true
     end
 
-    # Explicitly discard a failed runtime, wait for release, then Start from
-    # committed state. This loses unsaved memory; it never replaces a healthy
+    # Explicitly shut down a Computer that failed, wait for the shutdown, then
+    # Start from committed state. This loses unsaved memory; it never replaces a healthy
     # paused or running Computer and never silently follows failed Resume.
     def recover_computer(*args, **options)
       if args.first.is_a?(Computer::Credentials)
         credentials, *args = args
         options = credentials_options(credentials, options)
       end
-      start_existing_computer(*args, **options, recover_runtime: true)
+      start_existing_computer(*args, **options, recover: true)
     end
 
     def start_existing_computer(positional_id = nil, id: nil, key:, capture_keypair: nil, prior_capture_keypairs: [],
-                        binding_revision: 0, prior_keys: {}, ephemeral: false, location: nil, recover_runtime: false, **attach_opts)
+                        binding_revision: 0, prior_keys: {}, ephemeral: false, location: nil, recover: false, **attach_opts)
       if positional_id && id && positional_id != id
         raise ArgumentError, "attach_computer got two different ids (positional and id:)"
       end
@@ -305,22 +305,22 @@ module PineSandbox
       raise ArgumentError, "attach_computer requires the Computer id" if id.nil?
 
       provider = @connection.attach_provider
-      if recover_runtime && !provider.respond_to?(:current_binding)
+      if recover && !provider.respond_to?(:current_binding)
         raise ArgumentError, "saved-state recovery requires a provider with current_binding"
       end
       if provider.respond_to?(:current_binding)
         reference = provider.current_binding(id)
         binding_revision = reference.fetch("binding_revision")
-        if (runtime_id = reference["sandbox_id"])
+        if (sandbox_id = reference["sandbox_id"])
           begin
-            runtime = @connection.control_plane.get(runtime_id)
-            unless runtime.status == :terminated && runtime.reason == "COMPUTE_RELEASED"
-              unless recover_runtime || runtime.status == :stopping
-                raise RuntimeRetainedError.new(runtime_id: runtime_id, state: runtime.status)
+            sandbox = @connection.control_plane.get(sandbox_id)
+            unless sandbox.status == :terminated && sandbox.reason == "COMPUTE_RELEASED"
+              unless recover || sandbox.status == :stopping
+                raise SandboxRetainedError.new(sandbox_id: sandbox_id, state: sandbox.status)
               end
-              handle = RuntimeHandle.new(control_plane: @connection.control_plane, runtime_id: runtime_id)
-              unless handle.release_failed_runtime(runtime)
-                raise TimeoutError, "Old runtime release is unconfirmed; no replacement was allocated"
+              handle = SandboxHandle.new(control_plane: @connection.control_plane, sandbox_id: sandbox_id)
+              unless handle.release_failed_sandbox(sandbox)
+                raise TimeoutError, "The failed Computer's shutdown is unconfirmed; nothing was started"
               end
             end
           rescue NotFoundError
@@ -343,14 +343,14 @@ module PineSandbox
     alias_method :attach_computer, :start_computer
 
     # Adopt an ALREADY-bound, still-live Computer from its persisted `{id, key,
-    # runtime_id, ct_}` — NO new runtime, NO re-bind. For driving a running Computer
+    # sandbox_id, ct_}` — NO new start, NO re-bind. For driving a running Computer
     # across requests (e.g. re-minting a desktop `dt_` for a reconnect) from a
-    # backend that cached the `ct_`. Use #start_computer to restore onto a fresh runtime.
-    # `sandbox_id:` is the deprecated spelling of `runtime_id:`.
-    def adopt_existing(id:, key:, computer_token:, runtime_id: nil, sandbox_id: nil, status: :running,
+    # backend that cached the `ct_`. Use #start_computer to start it again with state
+    # restored.
+    def adopt_existing(id:, key:, sandbox_id:, computer_token:, status: :running,
                        binding_revision: 0, ephemeral: false)
       Computer.new(id, key: key, binding_revision: binding_revision, ephemeral: ephemeral)
-              .adopt(@connection, runtime_id: runtime_id || sandbox_id, computer_token: computer_token,
+              .adopt(@connection, sandbox_id: sandbox_id, computer_token: computer_token,
                      status: status, binding_revision: binding_revision)
     end
 
@@ -366,7 +366,7 @@ module PineSandbox
         raise ArgumentError, "credentials and binding belong to different Computers"
       end
       computer = adopt_existing(id: credentials.id.dup, key: credentials.key.dup,
-                                runtime_id: binding.runtime_id.dup, computer_token: binding.computer_token.dup,
+                                sandbox_id: binding.sandbox_id.dup, computer_token: binding.computer_token.dup,
                                 binding_revision: binding.binding_revision, ephemeral: credentials.ephemeral)
       configure_capture_keypairs(computer, credentials.capture_keypair, credentials.prior_capture_keypairs)
       credentials.prior_keys.each { |version, key| computer.add_prior_key(version, key.dup) }
@@ -374,18 +374,41 @@ module PineSandbox
     end
 
     # Block form: yields a ready Computer and stops it on exit.
-    # Failed saves and unconfirmed deletion are raised to the caller.
+    # Failed saves and unconfirmed deletion are raised to the caller. When the
+    # block raises, its error propagates and a failed Stop is only warned about.
     def with_computer(**opts)
       computer = create_computer(**opts)
-      yield computer
-    ensure
-      if computer && !computer.stop
-        raise TimeoutError, "Computer #{computer.id} stop is unconfirmed; retry Stop with its saved binding"
+      failure = nil
+      begin
+        yield computer
+      rescue Exception => e # rubocop:disable Lint/RescueException -- recorded, then re-raised
+        failure = e
+        raise
+      ensure
+        # Also runs when the block leaves early with return, break or throw.
+        if failure
+          stop_after_failure(computer, failure)
+        elsif !computer.stop
+          raise TimeoutError, "Computer #{computer.id} stop is unconfirmed; retry Stop with its saved binding"
+        end
       end
     end
 
     private
 
+    # Stop after with_computer's block failed: the block's error is the one the
+    # caller gets, so a Stop that fails or stays unconfirmed is only reported.
+    # The failure is recorded where the block raised, never read from $!, which
+    # inside a caller's own rescue clause is the exception that clause handles.
+    def stop_after_failure(computer, failure)
+      return if computer.stop
+
+      warn "PineSandbox: Computer #{computer.id} stop is unconfirmed; retry Stop with its saved binding " \
+           "(while #{failure.class} propagates)"
+    rescue StandardError => e
+      warn "PineSandbox: Computer #{computer.id} stop failed (#{e.class}: #{e.message}) while #{failure.class} propagates"
+    end
+
     def credentials_options(credentials, options)
       unless credentials.is_a?(Computer::Credentials)
         raise ArgumentError, "credentials must be a PineSandbox::Computer::Credentials"
@@ -401,13 +424,13 @@ module PineSandbox
       computer.attach(@connection, **attach_opts)
     rescue StandardError => e
       revision = computer.binding_revision
-      runtime_id = computer.last_authorized_runtime_id
-      raise if revision <= initial_revision || runtime_id.to_s.empty?
+      sandbox_id = computer.last_authorized_sandbox_id
+      raise if revision <= initial_revision || sandbox_id.to_s.empty?
 
       raise AttachAuthorizationCommittedError.new(
-        "attach authorization committed at revision #{revision} for runtime #{runtime_id}, " \
+        "attach authorization committed at revision #{revision} for Computer sandbox #{sandbox_id}, " \
         "but the bind failed: #{e.message}",
-        binding_revision: revision, runtime_id: runtime_id,
+        binding_revision: revision, sandbox_id: sandbox_id,
         credentials: recovery_credentials,
         status: (e.respond_to?(:status) ? e.status : nil), cause: e
       )