pinesandbox 0.0.1 → 0.3.18

data/lib/pinesandbox/client.rb

@@ -0,0 +1,446 @@
+require "securerandom"
+require_relative "zone"
+require_relative "delegated_connection"
+require_relative "control_token_source"
+require_relative "attach_credentials_source"
+require_relative "control_plane"
+require_relative "connection"
+require_relative "computer"
+require_relative "diagnostics"
+
+module PineSandbox
+  # The SDK entry point. Holds the project credential (`pk_`) + the endpoint
+  # ONCE, and returns ready Computers. Construction details (token mint+cache,
+  # attach-credential provider, control-plane client, host derivation) are
+  # internal — the operational API (Computer / Session) is unchanged.
+  #
+  # Attach authorization is portal-issued (AUTH_REDESIGN: portal-as-issuer) —
+  # the SDK exchanges the pk_ for per-attach authorization at attach time;
+  # Portal lazily creates only its minimal ownership row in that transaction:
+  #
+  #   client = PineSandbox::Client.new(
+  #     api_key:  ENV.fetch("PINE_SANDBOX_API_KEY"),   # "pk_…"
+  #     endpoint: ENV.fetch("PINE_SANDBOX_ENDPOINT"),  # URL or domain the portal shows
+  #   )
+  #   computer = client.create_computer            # NEW Computer — persist computer.id + computer.key
+  #   computer = client.attach_computer(id, key:)  # re-attach an existing one (state restored)
+  #
+  # `attach_credentials_provider:` / `control_token_provider:` are the seams
+  # for in-process issuers (e.g. the portal's own playground, which IS the
+  # issuer and skips the self-HTTP hop).
+  class Client
+    # Wraps a caller-supplied `-> { jws }` provider as a token source for shops that
+    # centralize minting (or a future local-sign path). The SDK does no caching here
+    # — the provider owns expiry/refresh.
+    class CallableTokenSource
+      def initialize(callable)
+        @callable = callable
+      end
+
+      def token(force_refresh: false)
+        @callable.call
+      end
+
+      def inspect
+        "#<PineSandbox::Client::CallableTokenSource [provider redacted]>"
+      end
+      alias_method :to_s, :inspect
+    end
+
+    # Wraps a caller-supplied `->(computer_id:, pod_uid:, coord_boot_id:) { … }`
+    # provider as an attach-credential source for in-process issuers (the
+    # portal's own playground mints without a self-HTTP hop). The callable owns
+    # authorization; it receives the full v3 mint keyword set and must return
+    # bind_token, broker_grant, key_assertion, and binding_revision.
+    class CallableAttachCredentialsSource
+      def initialize(callable)
+        @callable = callable
+      end
+
+      def credentials(computer_id:, pod_uid:, coord_boot_id:, sandbox_id:,
+                      expected_binding_revision:, idempotency_key:,
+                      pk_computer: nil, key_generation: nil, location: nil)
+        kwargs = { computer_id: computer_id, pod_uid: pod_uid, coord_boot_id: coord_boot_id,
+                   sandbox_id: sandbox_id, pk_computer: pk_computer,
+                   key_generation: key_generation,
+                   expected_binding_revision: expected_binding_revision,
+                   idempotency_key: idempotency_key }
+        kwargs[:location] = location if location
+        result = @callable.call(**kwargs)
+        unless result.is_a?(Hash)
+          raise AttachCredentialsError.new("attach_credentials_provider must return a Hash with bind_token + broker_grant")
+        end
+
+        normalized = result.transform_keys(&:to_s)
+        # key_assertion is required only for a persistent (v3) attach — the same
+        # attach that submits pk_computer. An ephemeral attach omits both.
+        key_assertion_missing = !pk_computer.to_s.empty? && normalized["key_assertion"].to_s.empty?
+        if normalized["bind_token"].to_s.empty? || normalized["broker_grant"].to_s.empty? ||
+           key_assertion_missing || normalized["binding_revision"].to_i <= expected_binding_revision
+          raise AttachCredentialsError.new(
+            "attach_credentials_provider result missing bind_token/broker_grant/key_assertion/binding_revision"
+          )
+        end
+        normalized
+      end
+
+      def inspect
+        "#<PineSandbox::Client::CallableAttachCredentialsSource [provider redacted]>"
+      end
+      alias_method :to_s, :inspect
+    end
+
+    # `clock:` (@api private) replaces the SDK's view of time — every wait,
+    # deadline and jitter — for tests that run retries on a virtual clock.
+    def initialize(endpoint: nil, api_key: nil,
+                   control_host: nil, spec_version: DelegatedConnection::SPEC_VERSION,
+                   control_token_provider: nil, attach_credentials_provider: nil,
+                   gateway_url: nil, clock: PineSandbox::SYSTEM_CLOCK)
+      raise ArgumentError, "endpoint required (e.g. \"https://pinesandbox.io\")" if endpoint.nil?
+
+      @zone =
+        if endpoint.is_a?(PineSandbox::Zone)
+          raise ArgumentError, "pass gateway_url to the Zone, not with one" unless gateway_url.nil?
+
+          endpoint
+        else
+          PineSandbox::Zone.new(endpoint, control_host: control_host, gateway_url: gateway_url)
+        end
+      @spec_version = spec_version
+      @diagnostics = Diagnostics.new(api_key: api_key, zone: @zone) unless api_key.to_s.empty?
+
+      token_source =
+        if control_token_provider
+          CallableTokenSource.new(control_token_provider)
+        else
+          raise ArgumentError, "api_key required (a pk_ client key) unless control_token_provider is given" if api_key.to_s.empty?
+
+          ControlTokenSource.new(api_key: api_key, host: @zone.control_host, protocol: @zone.http_scheme,
+                                 gateway_url: @zone.gateway_url, clock: -> { clock.now },
+                                 sleeper: ->(seconds) { clock.sleep(seconds) }, random: -> { clock.rand })
+        end
+
+      # Attach authorization. Default: the pk_-backed portal attach-credentials
+      # provider; `attach_credentials_provider:` is the in-process issuer seam.
+      attach_provider =
+        if attach_credentials_provider
+          if attach_credentials_provider.respond_to?(:credentials)
+            attach_credentials_provider
+          else
+            CallableAttachCredentialsSource.new(attach_credentials_provider)
+          end
+        elsif !api_key.to_s.empty?
+          AttachCredentialsSource.new(api_key: api_key, host: @zone.control_host, protocol: @zone.http_scheme,
+                                      gateway_url: @zone.gateway_url)
+        else
+          raise ArgumentError, "attach credentials unavailable: pass api_key (a pk_ client key) or attach_credentials_provider:"
+        end
+
+      @control_plane = ControlPlane.new(control_host: @zone.control_host, token_source: token_source,
+                                        protocol: @zone.http_scheme, spec_version: @spec_version,
+                                        gateway_url: @zone.gateway_url, clock: clock)
+      @connection = Connection.new(attach_provider: attach_provider, zone: @zone, control_plane: @control_plane,
+                                   clock: clock)
+    end
+
+    # @api private — retained for compatibility; applications use Computer operations.
+    attr_reader :control_plane
+    attr_reader :zone
+
+    # Queue a read-only check. The returned Hash contains a support reference;
+    # it does not open a support ticket or repeat customer work. Reuse an explicit
+    # idempotency_key after an uncertain response to retrieve the same request.
+    def create_diagnostic(computer_id:, session: nil, request_id: nil, description: nil, idempotency_key: SecureRandom.uuid)
+      raise ArgumentError, "diagnostics requires a project API key" unless @diagnostics
+
+      @diagnostics.create(computer_id: computer_id, session: session, request_id: request_id,
+                          description: description, idempotency_key: idempotency_key)
+    end
+
+    # Read the saved result without scheduling work. The Hash uses string keys.
+    def get_diagnostic(id)
+      raise ArgumentError, "diagnostics requires a project API key" unless @diagnostics
+
+      @diagnostics.get(id)
+    end
+
+    # Both successful diagnostic responses and PortalError expose Retry-After.
+    def diagnostic_response_metadata? = true
+
+    # Discover project-visible country intents before creating a Computer.
+    def available_locations
+      provider = @connection.attach_provider
+      unless provider.respond_to?(:available_locations)
+        raise LocationDiscoveryError, "location discovery is unavailable from the custom attach credentials provider"
+      end
+      provider.available_locations
+    end
+
+    # Optional configuration discovery, not a runtime 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)
+
+      provider.project_policy
+    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,
+    # already-deleted, and other projects' ids all return true. No undelete.
+    def delete_computer(computer)
+      computer_id =
+        case computer
+        when Computer then computer.id
+        when String then computer
+        else raise ArgumentError, "delete_computer expects a PineSandbox::Computer or a computer_id String"
+        end
+      raise ArgumentError, "computer_id required" if computer_id.empty?
+
+      provider = @connection.attach_provider
+      unless provider.respond_to?(:delete_computer)
+        raise ComputerDeletionError, "computer deletion is unavailable from the custom attach credentials provider"
+      end
+
+      computer.kill if computer.is_a?(Computer)
+      provider.delete_computer(computer_id)
+      true
+    end
+
+    # Provision a NEW persistent Computer (fresh UUIDv7 id + random 32-byte state key),
+    # bind it, and return it ready. Pass saved Computer::Credentials for crash-safe
+    # creation, or save computer.credentials from the returned Computer.
+    #
+    # `ephemeral: true` provisions an access-lease-only Computer that persists
+    # NOTHING — no capture keypair is generated or required, no state key is
+    # sealed into the bind, and #stop skips the pre-stop checkpoint.
+    def create_computer(credentials = nil, **options)
+      options = credentials_options(credentials, options) unless credentials.nil?
+      create_new_computer(**options)
+    end
+
+    def create_new_computer(id: nil, key: nil, capture_keypair: nil, prior_capture_keypairs: [],
+                            prior_keys: {}, ephemeral: false, location: nil, **attach_opts)
+      # An ephemeral Computer never carries a capture keypair, so only its id/key
+      # are ever generated; a persistent Computer also generates the keypair.
+      needs_generation = id.nil? || key.nil? || (!ephemeral && capture_keypair.nil?)
+      generated = Computer.generate_credentials(ephemeral: ephemeral) if needs_generation
+      cid = id || generated.id
+      state_key = key || generated.key
+      computer = Computer.new(cid, key: state_key, **(ephemeral ? { ephemeral: true } : {}))
+      capture_keypair ||= generated&.capture_keypair
+      configure_capture_keypairs(computer, capture_keypair, prior_capture_keypairs)
+      prior_keys.each { |version, bytes| computer.add_prior_key(version, bytes) }
+      recovery_credentials = computer.credentials
+      attach_opts = attach_opts.merge(location: location) if location
+      attach_with_recovery_context(
+        computer, initial_revision: 0, recovery_credentials: recovery_credentials, **attach_opts
+      )
+    end
+
+    private :create_new_computer
+
+    # Compatibility helper for integrations that explicitly pre-register a
+    # computer_id. Normal create/attach does not call this: first attach lazily
+    # creates Portal's minimal authorization row atomically with the binding.
+    def register_computer(computer_id, location: nil)
+      provider = @connection.attach_provider
+      return unless provider.respond_to?(:register_computer)
+
+      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.
+    # The id may be given positionally or as `id:` (matching #create_computer).
+    def start_computer(*args, **options)
+      if args.first.is_a?(Computer::Credentials)
+        unless @connection.attach_provider.respond_to?(:current_binding)
+          raise ArgumentError, "Start with saved credentials requires a provider with current_binding"
+        end
+        credentials, *args = args
+        options = credentials_options(credentials, options)
+      end
+      start_existing_computer(*args, **options, recover_runtime: 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
+    # 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)
+      provider = @connection.attach_provider
+      unless provider.respond_to?(:current_binding)
+        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?
+
+      RuntimeHandle.new(control_plane: @connection.control_plane, runtime_id: runtime_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
+    # 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)
+    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)
+      if positional_id && id && positional_id != id
+        raise ArgumentError, "attach_computer got two different ids (positional and id:)"
+      end
+      id ||= positional_id
+      raise ArgumentError, "attach_computer requires the Computer id" if id.nil?
+
+      provider = @connection.attach_provider
+      if recover_runtime && !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"])
+          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)
+              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"
+              end
+            end
+          rescue NotFoundError
+            # Authoritative project-scoped absence allows ordinary Start.
+          end
+        end
+      end
+
+      computer = Computer.new(id, key: key, binding_revision: binding_revision,
+                              **(ephemeral ? { ephemeral: true } : {}))
+      configure_capture_keypairs(computer, capture_keypair, prior_capture_keypairs)
+      prior_keys.each { |version, bytes| computer.add_prior_key(version, bytes) }
+      attach_opts = attach_opts.merge(location: location) if location
+      attach_with_recovery_context(computer, initial_revision: binding_revision, **attach_opts)
+    end
+
+    private :start_existing_computer
+
+    # Compatibility name for saved-state Start; never a memory Resume.
+    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
+    # 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,
+                       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,
+                     status: status, binding_revision: binding_revision)
+    end
+
+    # Reconstruct exactly the saved binding, without network I/O. A subsequent
+    # status/action reports whether it still exists; reconnect never allocates.
+    def reconnect_computer(credentials, binding:)
+      unless credentials.is_a?(Computer::Credentials) && binding.is_a?(Computer::Binding)
+        raise ArgumentError, "reconnect requires Computer credentials and binding"
+      end
+      credentials.validate!
+      binding.validate!
+      unless credentials.id == binding.computer_id
+        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,
+                                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) }
+      computer
+    end
+
+    # Block form: yields a ready Computer and stops it on exit.
+    # Failed saves and unconfirmed deletion are raised to the caller.
+    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"
+      end
+    end
+
+    private
+
+    def credentials_options(credentials, options)
+      unless credentials.is_a?(Computer::Credentials)
+        raise ArgumentError, "credentials must be a PineSandbox::Computer::Credentials"
+      end
+      credentials.validate!
+      if (options.keys & credentials.members).any?
+        raise ArgumentError, "pass credentials or individual identity/key options, not both"
+      end
+      credentials.to_h.merge(options)
+    end
+
+    def attach_with_recovery_context(computer, initial_revision:, recovery_credentials: nil, **attach_opts)
+      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?
+
+      raise AttachAuthorizationCommittedError.new(
+        "attach authorization committed at revision #{revision} for runtime #{runtime_id}, " \
+        "but the bind failed: #{e.message}",
+        binding_revision: revision, runtime_id: runtime_id,
+        credentials: recovery_credentials,
+        status: (e.respond_to?(:status) ? e.status : nil), cause: e
+      )
+    end
+
+    def configure_capture_keypairs(computer, current, prior)
+      prior = Array(prior)
+      unless current.nil? || current.is_a?(CaptureKeypair)
+        raise ArgumentError, "capture_keypair must be a PineSandbox::CaptureKeypair"
+      end
+      unless prior.all? { |keypair| keypair.is_a?(CaptureKeypair) }
+        raise ArgumentError, "prior_capture_keypairs must contain only PineSandbox::CaptureKeypair values"
+      end
+      if prior.any? && current.nil?
+        raise ArgumentError, "prior_capture_keypairs require capture_keypair"
+      end
+      if current
+        generations = prior.map(&:generation)
+        duplicate = generations.tally.find { |_generation, count| count > 1 }&.first
+        raise ArgumentError, "duplicate prior capture keypair generation #{duplicate}" if duplicate
+
+        invalid = prior.find { |keypair| keypair.generation >= current.generation }
+        if invalid
+          raise ArgumentError,
+                "prior capture keypair generation #{invalid.generation} must be below the current generation #{current.generation}"
+        end
+      end
+
+      # Apply only after the complete option set passes validation. This keeps
+      # create_computer side-effect-free on bad input: no partial key setup and
+      # no ownership registration request.
+      computer.set_capture_keypair(current) if current
+      prior.each { |keypair| computer.add_prior_capture_keypair(keypair) }
+    end
+  end
+end

data/lib/pinesandbox/clock.rb

@@ -0,0 +1,51 @@
+module PineSandbox
+  # @api private — the SDK's view of time. Every wait, deadline and jitter the
+  # SDK uses goes through one of these, so a test can substitute a virtual
+  # clock (a sleep returns at once, advances the clock and is recorded) and
+  # assert the exact waits. Production uses SystemClock.
+  class SystemClock
+    # Seconds on a monotonic clock, for deadlines and elapsed time.
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # Wall-clock time, for token expiry.
+    def now = Time.now
+
+    def sleep(seconds)
+      Kernel.sleep(seconds) if seconds.positive?
+    end
+
+    # A uniform random Float in [0, 1), for jitter.
+    def rand = Kernel.rand
+  end
+
+  # @api private
+  SYSTEM_CLOCK = SystemClock.new
+
+  # @api private — the shared client policy (computer-api.yaml x-pine-retry.client).
+  module RetryPolicy
+    # A replay-safe request is sent at most this many times after a transport fault.
+    TRANSIENT_ATTEMPTS = 3
+    TRANSIENT_BASE = 0.2
+    TRANSIENT_JITTER = 0.1
+    TRANSIENT_CAP = 2.0
+
+    # An event stream reconnects at most this many times in a row without
+    # delivering an event, then raises StreamLostError.
+    STREAM_RECONNECT_BUDGET = 5
+    STREAM_BASE = 0.5
+    STREAM_JITTER = 0.2
+    STREAM_CAP = 5.0
+
+    module_function
+
+    # The wait before transient retry `attempt` (1-based).
+    def transient_backoff(attempt, clock)
+      [TRANSIENT_BASE * (2**(attempt - 1)) + clock.rand * TRANSIENT_JITTER, TRANSIENT_CAP].min
+    end
+
+    # The wait before stream reconnect `attempt` (1-based).
+    def stream_backoff(attempt, clock)
+      [STREAM_BASE * (2**(attempt - 1)) + clock.rand * STREAM_JITTER, STREAM_CAP].min
+    end
+  end
+end