pinesandbox 0.3.18 → 0.3.20

data/lib/pinesandbox/attach_credentials_source.rb

@@ -1,5 +1,6 @@
 require "faraday"
 require "json"
+require "time"
 require_relative "errors"
 
 module PineSandbox
@@ -12,17 +13,19 @@ module PineSandbox
   #   * POST /v1/computers                                — optional legacy
   #     pre-registration helper. Normal attach does not require it.
   #   * POST /v1/computers/:computer_id/attach-credentials — body carries the
-  #     runtime coordinates {pod_uid, coord_boot_id}; returns {bind_token,
+  #     start's coordinates {pod_uid, coord_boot_id}; returns {bind_token,
   #     broker_grant, key_assertion, binding_revision}. The portal authenticates
   #     the pk_ and atomically creates/rechecks its minimal authorization row,
   #     advances the key floor, supersedes the prior binding, and mints.
   #   * DELETE /v1/computers/:computer_id                 — permanent delete.
   #     204 for deleted, already deleted, unknown, and cross-project ids alike.
+  #   * POST /v1/computers/:computer_id/artifacts/token   — a short-lived
+  #     storage token for the Computer's artifacts (Artifacts).
   #
-  # This source caches nothing. Computer#run_bind calls it exactly once for a
-  # sandbox, then convergence retries re-send the held envelope verbatim
-  # (the bind is idempotent on jti + ciphertext). A runtime-identity shift
-  # requires a fresh sandbox; it never authorizes the same sandbox twice.
+  # This source caches nothing. Computer#run_bind calls it exactly once for each
+  # start, then convergence retries re-send the held envelope verbatim
+  # (the bind is idempotent on jti + ciphertext). A change of pod_uid or
+  # coord_boot_id requires a new start; it never authorizes the same start twice.
   # The pk_ never appears in #inspect.
   class AttachCredentialsSource
     REGISTER_PATH = "/v1/computers"
@@ -97,7 +100,31 @@ module PineSandbox
       payload
     end
 
-    # One authorization-registry read before Start; never a runtime status poll.
+    # A short-lived storage token for the Computer's artifacts, and where they
+    # are: "access_token", "expires_at", "endpoint", "bucket", "prefix",
+    # "writable", "used_bytes" and "limit_bytes". With `copy_from` (other
+    # Computer ids of the project), it may also read their artifacts, and
+    # "copy_from" maps each id to its prefix. Works whether or not the
+    # Computer is running. Returns the response Hash.
+    def artifact_token(computer_id, copy_from: nil)
+      raise ArgumentError, "computer_id required" if computer_id.to_s.empty?
+
+      copy_from = Array(copy_from).map(&:to_s)
+      body = copy_from.empty? ? {} : { copy_from: copy_from }
+      resp = post("#{REGISTER_PATH}/#{computer_id}/artifacts/token", json: body, op: "artifact token")
+      if resp.status == 404
+        raise UnknownComputerError.new(error_message(resp, "Computer not found"), **error_attributes(resp))
+      end
+      raise PortalError.new(error_message(resp, "Artifact token unavailable"), **error_attributes(resp)) unless resp.status == 200
+
+      payload = parse_json(resp)
+      unless artifact_token?(payload, copy_from)
+        raise PortalError.new("Invalid artifact token response", **error_attributes(resp))
+      end
+      payload
+    end
+
+    # One authorization-registry read before Start; never a Computer status poll.
     def current_binding(computer_id)
       resp = get("#{REGISTER_PATH}/#{computer_id}", op: "computer binding lookup")
       if resp.status == 404
@@ -114,7 +141,7 @@ module PineSandbox
 
     # Permanently delete `computer_id`. The portal tombstones it at once (no
     # further attach, renewal, or lease refresh), destroys its bound sandboxes
-    # asynchronously, keeps saved browser state for 24 hours before purging it,
+    # asynchronously, keeps saved browser state for 25 hours before purging it,
     # and never accepts the id again. Idempotent and non-disclosing: an unknown,
     # already-deleted, or cross-project id is the same 204. Returns true.
     def delete_computer(computer_id)
@@ -134,9 +161,9 @@ module PineSandbox
       end
     end
 
-    # Mint the per-attach credentials for one runtime + boot. `sandbox_id` is the
-    # provisioned sandbox this attach targets — the portal records the
-    # sandbox→computer attribution at mint (its renewal gate keys off it).
+    # Mint the per-attach credentials for one Computer sandbox and boot. `sandbox_id`
+    # is the sandbox id this attach targets — the portal records which Computer it
+    # belongs to at mint (its renewal gate keys off it).
     # Returns a Hash with string keys: "bind_token", "broker_grant",
     # "key_assertion", "binding_revision", and the effective "location"
     # (plus expiry metadata).
@@ -208,13 +235,15 @@ module PineSandbox
         )
       when 412
         problem = parse_json(resp)
+        # A Portal that predates current_revision sends only current_binding_revision.
+        revision = problem.fetch("current_revision") { problem["current_binding_revision"] }
         raise BindingRevisionConflictError.new(
           binding_conflict_message(
             error_message(resp, "binding revision changed; reload and adopt the winning binding"),
-            problem["current_binding_revision"], problem["current_sandbox_id"]
+            revision, problem["current_sandbox_id"]
           ),
-          current_binding_revision: problem["current_binding_revision"],
-          current_runtime_id: problem["current_sandbox_id"],
+          current_binding_revision: revision,
+          current_sandbox_id: problem["current_sandbox_id"],
           **error_attributes(resp)
         )
       else
@@ -243,6 +272,19 @@ module PineSandbox
       { country: normalized.fetch("country") }
     end
 
+    def artifact_token?(payload, copy_from)
+      return false unless payload.is_a?(Hash)
+      return false unless %w[access_token expires_at endpoint bucket].all? { |key| payload[key].is_a?(String) && !payload[key].empty? }
+      return false unless payload["prefix"].is_a?(String) && [true, false].include?(payload["writable"])
+      return false unless payload["used_bytes"].is_a?(Integer) && payload["limit_bytes"].is_a?(Integer)
+
+      Time.iso8601(payload["expires_at"])
+      prefixes = payload["copy_from"] || {}
+      prefixes.is_a?(Hash) && copy_from.all? { |id| prefixes[id].is_a?(String) }
+    rescue ArgumentError
+      false
+    end
+
     def response_location?(value)
       value.is_a?(Hash) && value["country"].is_a?(String) &&
         value["country"].match?(/\A[A-Z]{2}\z/)
@@ -347,12 +389,12 @@ module PineSandbox
 
     # The attach revision is a fence against two live attaches of one
     # Computer, so the SDK never retries past it; the message says what to do.
-    def binding_conflict_message(message, current_revision, current_runtime_id)
+    def binding_conflict_message(message, current_revision, current_sandbox_id)
       return message unless current_revision.is_a?(Integer)
 
-      holder = current_runtime_id.to_s.empty? ? "" : " (runtime #{current_runtime_id})"
+      holder = current_sandbox_id.to_s.empty? ? "" : " (Computer sandbox #{current_sandbox_id})"
       "#{message}. Another start changed the Computer binding#{holder}. " \
-        "Do not retry automatically. Check the current runtime before starting again."
+        "Do not retry automatically. Check whether the Computer is still running before starting again."
     end
 
     def error_message(resp, default)

data/lib/pinesandbox/bind_hpke.rb

@@ -15,7 +15,7 @@ module PineSandbox
     module_function
 
     # info binds the sealed payload to the receiving process identity so a
-    # ciphertext sealed for one runtime/boot cannot be opened by another.
+    # ciphertext sealed for one Computer sandbox/boot cannot be opened by another.
     # MUST byte-match the receiver's info string.
     #
     # @param pod_uid [String]
@@ -26,8 +26,8 @@ module PineSandbox
     end
 
     # restore_info is the two-round v3 restore's round-2 domain: the
-    # integrator-unwrapped component secrets sealed back to the same runtime
-    # key. Same suite, DISTINCT domain — a bind ciphertext can never be
+    # integrator-unwrapped component secrets sealed back to the same Computer
+    # sandbox key. Same suite, DISTINCT domain — a bind ciphertext can never be
     # replayed as a secrets payload or vice versa. MUST byte-match the
     # receiver's restore info string.
     def restore_info(pod_uid, coord_boot_id)
@@ -36,7 +36,7 @@ module PineSandbox
 
     # seal encrypts plaintext to the recipient's raw 32-byte X25519 public
     # key. The AAD is fixed empty (the portal attach path carries no nonce —
-    # payload-to-runtime binding lives in the info string).
+    # payload-to-sandbox binding lives in the info string).
     #
     # @param recipient_pub_raw [String] 32 raw bytes (NOT base64).
     # @param plaintext [String] bytes to seal.

data/lib/pinesandbox/client.rb

@@ -7,6 +7,7 @@ require_relative "control_plane"
 require_relative "connection"
 require_relative "computer"
 require_relative "diagnostics"
+require_relative "artifacts"
 
 module PineSandbox
   # The SDK entry point. Holds the project credential (`pk_`) + the endpoint
@@ -107,6 +108,7 @@ module PineSandbox
           PineSandbox::Zone.new(endpoint, control_host: control_host, gateway_url: gateway_url)
         end
       @spec_version = spec_version
+      @clock = clock
       @diagnostics = Diagnostics.new(api_key: api_key, zone: @zone) unless api_key.to_s.empty?
 
       token_source =
@@ -176,7 +178,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)
@@ -184,12 +186,25 @@ module PineSandbox
       provider.project_policy
     end
 
+    # A Computer's artifacts, running or stopped: the files it keeps beyond
+    # its sessions, to list, upload, download, open, copy and delete (see
+    # Artifacts). Needs the project API key; no request is sent until the
+    # first operation.
+    def artifacts(computer_id)
+      raise ArgumentError, "id must be a lowercase UUIDv7" unless computer_id.to_s.match?(Computer::UUID_V7)
+
+      provider = @connection.attach_provider
+      raise ArgumentError, "artifacts require a project API key provider" unless provider.respond_to?(:artifact_token)
+
+      Artifacts.new(computer_id: computer_id, token_source: provider, clock: @clock)
+    end
+
     # PERMANENTLY delete a Computer: its identity and saved state end (stop
     # and kill keep both). Accepts a PineSandbox::Computer or its id String. A
     # Computer that is still attached is force-terminated first (#kill — no
     # final capture, the state is being deleted). The portal tombstones the id
     # immediately, destroys any remaining sandboxes asynchronously, purges saved
-    # state after 24 hours, and never accepts the id again. Idempotent: unknown,
+    # state after 25 hours, and never accepts the id again. Idempotent: unknown,
     # already-deleted, and other projects' ids all return true. No undelete.
     def delete_computer(computer)
       computer_id =
@@ -253,8 +268,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 +279,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 +292,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 +320,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 +358,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 +381,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 +389,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 +439,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
       )