pinesandbox 0.0.1 → 0.3.18

data/lib/pinesandbox/control_plane.rb

@@ -0,0 +1,341 @@
+require "faraday"
+require "json"
+require "time"
+require_relative "errors"
+require_relative "clock"
+require_relative "operations"
+require_relative "runtime_details"
+require_relative "spec_version_middleware"
+
+module PineSandbox
+  # The project-scoped control plane: create / inspect / destroy a Computer's pod at
+  # https://api.<zone>, authenticated with a project JWS (Bearer) from the
+  # ControlTokenSource. Spec-version rides the shared middleware. Contract:
+  # specs/computer-api.yaml lifecycle routes (root, no /v1).
+  # @api private
+  class ControlPlane
+    Runtime = Struct.new(:id, :image, :status, :metadata, :entrypoint,
+                         :expires_at, :created_at, :operation_id,
+                         :retryable, :reason, :message, :etag, :lifecycle, :runtime_revision, keyword_init: true)
+
+    # How often a keyed create the server answered busy (503
+    # COMPUTER_CREATE_BUSY) is repeated before that answer is raised.
+    MAX_BUSY_REPEATS = 10
+    BUSY_CODE = "COMPUTER_CREATE_BUSY".freeze
+
+    # max_transient_attempts: how many times a replay-safe request (per the
+    # public operation table) is sent on a transient transport failure
+    # (connection reset / timeout). clock drives deadlines, backoff and jitter;
+    # sleeper, when given, replaces only its waits (tests).
+    attr_reader :clock
+
+    def initialize(control_host:, token_source:, protocol: "https", spec_version: 1,
+                   open_timeout: 5, request_timeout: 30, connection: nil,
+                   max_transient_attempts: RetryPolicy::TRANSIENT_ATTEMPTS, sleeper: nil, gateway_url: nil,
+                   clock: PineSandbox::SYSTEM_CLOCK)
+      @control_host = control_host.to_s
+      @token_source = token_source
+      @protocol = protocol
+      @gateway_url = gateway_url
+      @spec_version = spec_version
+      @open_timeout = open_timeout
+      @request_timeout = request_timeout
+      @connection = connection
+      @max_transient_attempts = [max_transient_attempts.to_i, 1].max
+      @clock = clock
+      @sleeper = sleeper || ->(seconds) { @clock.sleep(seconds) }
+    end
+
+    # Internal adapter for the public Computer contract. No generic sandbox
+    # create, image selection or task dispatch is available through this client.
+    def create_computer(body:, request_timeout: nil)
+      # A create ID permits identical retries without extending runtime expiry.
+      keyed = !!body[:create_id]
+      deadline = monotonic_now + request_timeout if request_timeout
+      busy_repeats = 0
+      loop do
+        resp = authed(:post, "computer-sandboxes", retry_transient: keyed && replay_safe?("createComputer"),
+                                                   request_timeout: deadline && remaining_timeout(deadline)) do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+        # The server queues a burst of a project's creates only so far and
+        # asks the rest to come back. A keyed create repeats safely, so it
+        # waits and repeats while its deadline allows.
+        wait = busy_wait(resp) if keyed && busy_repeats < MAX_BUSY_REPEATS
+        return to_sandbox!(resp, ok: [200, 201, 202]) if wait.nil? || (deadline && wait >= deadline - monotonic_now)
+
+        busy_repeats += 1
+        @sleeper.call(wait)
+      end
+    end
+
+    def stop(sandbox_id, operation_id:, request_timeout: nil)
+      resp = authed(:post, "sandboxes/#{sandbox_id}/stop", retry_transient: replay_safe?("stopComputerRuntime"),
+                                                         request_timeout: request_timeout) do |req|
+        req.headers["Content-Type"] = "application/json"
+        req.body = JSON.generate(id: operation_id)
+      end
+      raise_for_status!(resp) unless [202, 404].include?(resp.status)
+      true
+    end
+
+    def set_idle_timeout(sandbox_id, seconds:, etag:)
+      raise BindError, "Server did not provide a conditional lifecycle observation" unless etag
+
+      resp = authed(:put, "sandboxes/#{sandbox_id}/idle-timeout", retry_transient: replay_safe?("setComputerIdleTimeout")) do |req|
+        req.headers["Content-Type"] = "application/json"
+        req.headers["If-Match"] = etag
+        req.body = JSON.generate(seconds: seconds)
+      end
+      to_sandbox!(resp, ok: [200])
+    end
+
+    # GET /sandboxes/{id}
+    def get(sandbox_id, request_timeout: nil)
+      resp = authed(:get, "sandboxes/#{sandbox_id}", retry_transient: replay_safe?("getComputer"), request_timeout: request_timeout)
+      to_sandbox!(resp, ok: [200])
+    end
+
+    # Reuse the status ETag across bounded waits. Any server can answer the
+    # wait; the client keeps no operation state.
+    def wait_for_change(sandbox_id, previous:, request_timeout:, interval: 2)
+      started = monotonic_now
+      deadline = started + request_timeout
+      begin
+        resp = authed(:get, "sandboxes/#{sandbox_id}", retry_transient: replay_safe?("getComputer"),
+                      request_timeout: [request_timeout, 35].min) do |req|
+          req.headers["If-None-Match"] = previous.etag if previous.etag
+        end
+        current = resp.status == 304 ? previous : to_sandbox!(resp, ok: [200])
+      rescue PineSandbox::ConnectionError, PineSandbox::TimeoutError, PineSandbox::ServerError => error
+        raise if error.is_a?(PineSandbox::ServerError) && ![502, 503, 504].include?(error.status)
+
+        # An observation failure changes no lifecycle state.
+        remaining_timeout(deadline)
+        current = previous
+      end
+      # Pace only quick, unchanged responses or failures. Time already spent
+      # waiting on the server counts; changed state never incurs this delay.
+      if current.status == previous.status && (current.etag.nil? || current.etag == previous.etag)
+        delay = interval - (monotonic_now - started)
+        @sleeper.call([delay, remaining_timeout(deadline)].min) if delay.positive?
+      end
+      current
+    end
+
+    # DELETE /sandboxes/{id} — idempotent (404 = already gone), so it is sent
+    # again after a transport fault, conditional or not.
+    def destroy(sandbox_id, request_timeout: nil, if_match: nil)
+      resp = authed(:delete, "sandboxes/#{sandbox_id}", retry_transient: replay_safe?("destroyComputer"),
+                                                       request_timeout: request_timeout) do |req|
+        req.headers["If-Match"] = if_match if if_match
+      end
+      raise_for_status!(resp) unless [200, 202, 204, 404].include?(resp.status)
+      true
+    end
+
+    # These methods report acceptance. RuntimeHandle waits for completion.
+    # Keep the boolean result for integrations using older Docker servers.
+    # Neither is replay-safe, so a transport fault raises instead of resending.
+    def pause(sandbox_id, request_timeout: nil)
+      resp = authed(:post, "sandboxes/#{sandbox_id}/pause", retry_transient: replay_safe?("pauseComputer"),
+                                                            request_timeout: request_timeout)
+      raise_for_status!(resp) unless [200, 202, 204, 409].include?(resp.status)
+      resp.status != 409
+    end
+
+    def resume(sandbox_id, request_timeout: nil)
+      resp = authed(:post, "sandboxes/#{sandbox_id}/resume", retry_transient: replay_safe?("resumeComputer"),
+                                                             request_timeout: request_timeout)
+      raise_for_status!(resp) unless [200, 202, 204, 409].include?(resp.status)
+      resp.status != 409
+    end
+
+    private
+
+    def replay_safe?(operation_id) = Operations.fetch(operation_id).replay_safe?
+
+    # Bearer the project JWS; on a 401 force ONE token refresh + retry once (the JWS
+    # likely expired). A 401 means the request was rejected, not applied — so retrying
+    # is safe even for create. When retry_transient is set (idempotent reads + keyed
+    # creates — see the call sites), a transient transport failure (connection reset /
+    # timeout) is also re-sent with bounded backoff. Legacy unkeyed creates
+    # remain single-shot on transport failure.
+    def authed(method, path, retry_transient: false, request_timeout: nil, &block)
+      attempt = 0
+      deadline = monotonic_now + request_timeout if request_timeout
+      begin
+        remaining_timeout(deadline)
+        resp = send_request(method, path, @token_source.token, deadline: deadline, &block)
+        return resp unless resp.status == 401
+
+        remaining_timeout(deadline)
+        send_request(method, path, @token_source.token(force_refresh: true), deadline: deadline, &block)
+      rescue PineSandbox::ConnectionError, PineSandbox::TimeoutError
+        attempt += 1
+        raise unless retry_transient && attempt < @max_transient_attempts
+        delay = transient_backoff(attempt)
+        delay = [delay, remaining_timeout(deadline)].min if deadline
+        @sleeper.call(delay)
+        retry
+      end
+    end
+
+    # Exponential backoff with small jitter, capped — for transient transport retries.
+    def transient_backoff(attempt)
+      RetryPolicy.transient_backoff(attempt, @clock)
+    end
+
+    def send_request(method, path, token, deadline: nil, &block)
+      remaining = remaining_timeout(deadline)
+      connection.public_send(method, path) do |req|
+        if remaining
+          req.options.timeout = remaining
+          req.options.open_timeout = [@open_timeout, remaining].min
+        end
+        req.headers["Authorization"] = "Bearer #{token}"
+        req.headers["Accept"] = "application/json"
+        block&.call(req)
+      end
+    rescue Faraday::TimeoutError => e
+      raise PineSandbox::TimeoutError,
+            PineSandbox.with_context("control plane request timed out: #{e.message}",
+                                     op: "#{method.upcase} /#{path.to_s.split("?").first}")
+    rescue Faraday::ConnectionFailed => e
+      raise PineSandbox::ConnectionError,
+            PineSandbox.with_context("control plane request failed: #{e.message}",
+                                     op: "#{method.upcase} /#{path.to_s.split("?").first}")
+    end
+
+    def remaining_timeout(deadline)
+      return unless deadline
+
+      remaining = deadline - monotonic_now
+      raise PineSandbox::TimeoutError, "control plane request deadline exceeded" if remaining <= 0
+
+      remaining
+    end
+
+    def monotonic_now
+      @clock.monotonic
+    end
+
+    def to_sandbox!(resp, ok:)
+      raise_for_status!(resp) unless ok.include?(resp.status)
+      payload = parse_json(resp)
+      Runtime.new(id: payload["id"], image: payload["image"], metadata: payload["metadata"] || {},
+                  entrypoint: payload["entrypoint"], status: runtime_state(payload.dig("status", "state")),
+                  expires_at: runtime_time(payload["expiresAt"]), created_at: runtime_time(payload["createdAt"]),
+                  lifecycle: RuntimeLifetime.from_payload(payload["lifecycle"]),
+                  runtime_revision: payload["runtime_revision"],
+                  operation_id: payload.dig("status", "operation_id"),
+                  retryable: payload.dig("status", "retryable"),
+                  reason: payload.dig("status", "reason"), message: payload.dig("status", "message"), etag: resp.headers["etag"])
+    end
+
+    # "Running" → :running, "PendingResume" → :pending_resume.
+    def runtime_state(state)
+      state&.to_s&.gsub(/([a-z\d])([A-Z])/, '\1_\2')&.downcase&.to_sym
+    end
+
+    def runtime_time(value) = value.nil? || value.is_a?(Time) ? value : Time.iso8601(value)
+
+    def raise_for_status!(resp)
+      body = parse_json(resp)
+      error_code = body.is_a?(Hash) ? body["code"] : nil
+      klass =
+        case resp.status
+        when 400 then PineSandbox::BadRequestError
+        when 401 then PineSandbox::UnauthorizedError
+        when 403 then PineSandbox::ForbiddenError
+        when 404 then PineSandbox::NotFoundError
+        when 409, 412 then PineSandbox::ConflictError
+        when 422 then PineSandbox::UnprocessableEntityError
+        when 429
+          case error_code
+          when PineSandbox::CapacityExceededError::CODE then PineSandbox::CapacityExceededError
+          when PineSandbox::CreateRateLimitedError::CODE then PineSandbox::CreateRateLimitedError
+          else PineSandbox::ApiError
+          end
+        when 500..599 then PineSandbox::ServerError
+        else PineSandbox::ApiError
+        end
+      # Control-plane errors are {code,message}, not problem+json, so they never carry
+      # request_id in the body — but the gateway still stamps X-Request-Id on every
+      # response. Capture it PLUS the operation ("<METHOD> /sandboxes/..." — WHICH operation,
+      # with the sandbox id in the path where the call is sandbox-scoped) into
+      # problem_extensions, so ApiError#build_message renders the resource-first context and
+      # #request_id is populated. No standalone sandbox_id here — this is the control plane;
+      # the op path already carries the id for get/destroy/pause/resume.
+      rid = resp.headers["x-request-id"] || resp.headers["X-Request-Id"]
+      op = op_for(resp)
+      ext = {}
+      ext["op"] = op if op && !op.to_s.empty?
+      ext["request_id"] = rid unless rid.to_s.empty?
+      fields = { status: resp.status, error_code: error_code, error_message: status_message(resp),
+                 response_body: resp.body.to_s, problem_extensions: (ext.empty? ? nil : ext) }
+      error = klass.new(**fields)
+      error.retry_after = retry_after(resp)
+      raise error
+    end
+
+    # Seconds to wait before repeating a create the server answered busy
+    # (503 COMPUTER_CREATE_BUSY); nil for any other answer.
+    def busy_wait(resp)
+      return unless resp.status == 503
+
+      body = parse_json(resp)
+      return unless body.is_a?(Hash) && body["code"] == BUSY_CODE
+
+      retry_after(resp) || 1
+    end
+
+    # Retry-After in whole seconds, the only form the lifecycle server sends;
+    # nil when absent or not a positive integer.
+    def retry_after(resp)
+      value = resp.headers["retry-after"].to_s.strip
+      seconds = value.match?(/\A\d+\z/) ? value.to_i : 0
+      seconds.positive? ? seconds : nil
+    end
+
+    # "<METHOD> <path>" off the Faraday response env — WHICH control-plane operation failed.
+    # nil when the env/url is unavailable (a diagnostic detail must never mask the real error).
+    def op_for(resp)
+      env = resp.respond_to?(:env) ? resp.env : nil
+      return nil unless env && env.method
+
+      url = env.url
+      path = url.respond_to?(:path) ? url.path : url.to_s
+      "#{env.method.to_s.upcase} #{path}"
+    rescue StandardError
+      nil
+    end
+
+    # Control-plane errors are {code,message}; bind/coord errors are RFC-9457
+    # problem+json {title,detail}. Surface whichever is present.
+    def status_message(resp)
+      body = parse_json(resp)
+      body["message"] || body["detail"] || body["title"] || body["error"] || "control plane error (HTTP #{resp.status})"
+    rescue StandardError
+      "control plane error (HTTP #{resp.status})"
+    end
+
+    def parse_json(resp)
+      return resp.body if resp.body.is_a?(Hash)
+      return {} if resp.body.to_s.empty?
+
+      JSON.parse(resp.body)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def connection
+      @connection ||= Zone.faraday(scheme: @protocol, host: @control_host, gateway_url: @gateway_url) do |f|
+        f.use PineSandbox::SpecVersionMiddleware, supported_major: @spec_version
+        f.options.open_timeout = @open_timeout
+        f.options.timeout = @request_timeout
+      end
+    end
+  end
+end

data/lib/pinesandbox/control_state.rb

@@ -0,0 +1,31 @@
+require "time"
+
+module PineSandbox
+  # A session's control state and its ETag, returned by Session#control_state,
+  # #update_control, #take_control and #release_control. It is the Hash those
+  # methods have always returned — `{ state: <ControlStateV1 Hash>, etag: }`,
+  # with `state` string-keyed as the wire sends it — with readers for the
+  # fields. Pass #etag as `if_match:` on the next update.
+  class ControlState < Hash
+    def self.wrap(state:, etag:)
+      new.update(state: state, etag: etag)
+    end
+
+    def state = self[:state]
+    def etag = self[:etag]
+
+    # Who drives the session: "human", "agent" or "locked".
+    def controller = field("controller")
+    def epoch = field("epoch")
+    def session_name = field("session_name")
+    def idle_paused = field("idle_paused")
+    def idle_deadline = field("idle_deadline")
+
+    private
+
+    def field(name)
+      body = state
+      body.is_a?(Hash) ? body[name] : nil
+    end
+  end
+end

data/lib/pinesandbox/control_token_source.rb

@@ -0,0 +1,232 @@
+require "faraday"
+require "base64"
+require "json"
+require "time"
+require_relative "errors"
+
+module PineSandbox
+  # Exchanges a project client key (`pk_…`) at the portal's `POST /v1/control-token`
+  # for a short-TTL EdDSA project JWS, and caches it until just before expiry.
+  # Freshness is derived from the token's own `exp` claim when present; the
+  # response expiry is only a fallback. The JWS is what the control plane
+  # (`api.<zone>`) accepts as `Authorization: Bearer`.
+  #
+  # Thread-safe with single-flight refresh (one mint in flight; concurrent callers
+  # reuse it). `429`/`5xx` are retried with bounded jittered backoff; a
+  # `Retry-After` is a floor on that wait, and one longer than the backoff cap
+  # ends the mint at once with the error carrying the server's wait
+  # (`#retry_after`) instead of retrying early. `401`/`403` are terminal. The `pk_` and the minted JWS never
+  # appear in `#inspect`. The clock, sleeper and jitter source are injectable for tests.
+  class ControlTokenSource
+    PATH = "/v1/control-token"
+    DEFAULT_SKEW_SECONDS = 60   # refresh this long before exp (mirrors the portal's iat/nbf back-date)
+    DEFAULT_MAX_ATTEMPTS = 4
+    MAX_BACKOFF_SECONDS = 10.0
+
+    def initialize(api_key:, host:, protocol: "https",
+                   clock: -> { Time.now }, sleeper: ->(s) { Kernel.sleep(s) }, random: -> { Kernel.rand },
+                   skew: DEFAULT_SKEW_SECONDS, max_attempts: DEFAULT_MAX_ATTEMPTS,
+                   open_timeout: 5, request_timeout: 30, connection: nil, gateway_url: nil)
+      raise ArgumentError, "api_key required (a pk_ client key)" if api_key.to_s.empty?
+
+      @api_key = api_key.to_s
+      @host = host.to_s
+      @protocol = protocol
+      @gateway_url = gateway_url
+      @clock = clock
+      @sleeper = sleeper
+      @random = random
+      @skew = skew.to_i
+      @max_attempts = [max_attempts.to_i, 1].max
+      @open_timeout = open_timeout
+      @request_timeout = request_timeout
+      @connection = connection
+      @mutex = Mutex.new
+      @token = nil
+      @expires_at = nil
+    end
+
+    # The current project JWS, minting/refreshing as needed. `force_refresh: true`
+    # bypasses the cache (used after a control-plane 401).
+    def token(force_refresh: false)
+      cached = @token
+      return cached if cached && !force_refresh && fresh?(@clock.call)
+
+      @mutex.synchronize do
+        return @token if @token && !force_refresh && fresh?(@clock.call)
+
+        mint!
+      end
+    end
+
+    def inspect
+      "#<PineSandbox::ControlTokenSource host=#{@host.inspect} cached=#{!@token.nil?} [pk_+token redacted]>"
+    end
+    alias_method :to_s, :inspect
+
+    private
+
+    def fresh?(now)
+      # @expires_at already reflects the token's own exp claim (compute_expiry prefers it
+      # over the response metadata at mint time), so freshness reads the cached value
+      # rather than re-parsing the JWS on every call.
+      @expires_at && now < (@expires_at - @skew)
+    end
+
+    def mint!
+      @max_attempts.times do |i|
+        last = (i + 1 >= @max_attempts)
+        begin
+          resp = post_mint
+        rescue PineSandbox::ConnectionError, PineSandbox::TimeoutError
+          # Transient (connection reset / timeout). Minting a token has no side
+          # effect, so it is always safe to retry with backoff.
+          raise if last
+          @sleeper.call(backoff(i + 1, nil))
+          next
+        end
+        case resp.status
+        when 200
+          return apply_success(resp)
+        when 401
+          raise InvalidClientKey.new(error_message(resp, "invalid or unknown project client key"),
+                                     status: 401, body: resp.body, request_id: request_id(resp), op: mint_op)
+        when 403
+          raise InsufficientScope.new(error_message(resp, "this key may not mint control-plane tokens (needs pk_session/pk_admin)"),
+                                      status: 403, body: resp.body, request_id: request_id(resp), op: mint_op)
+        when 429
+          retry_after = parse_retry_after(resp)
+          if last || beyond_cap?(retry_after)
+            raise RateLimited.new("portal rate-limited the control-token mint", status: 429,
+                                  body: resp.body, request_id: request_id(resp), op: mint_op, retry_after: retry_after)
+          end
+          @sleeper.call(backoff(i + 1, retry_after))
+        when 500..599
+          retry_after = parse_retry_after(resp)
+          if last || beyond_cap?(retry_after)
+            raise ControlTokenError.new("portal error minting control token", status: resp.status,
+                                        body: resp.body, request_id: request_id(resp), op: mint_op,
+                                        retry_after: retry_after)
+          end
+          @sleeper.call(backoff(i + 1, retry_after))
+        else
+          raise ControlTokenError.new("unexpected portal response minting control token",
+                                      status: resp.status, body: resp.body, request_id: request_id(resp), op: mint_op)
+        end
+      end
+    end
+
+    def post_mint
+      connection.post(PATH) do |req|
+        req.headers["Authorization"] = "Bearer #{@api_key}"
+        req.headers["Accept"] = "application/json"
+      end
+    rescue Faraday::TimeoutError => e
+      raise PineSandbox::TimeoutError,
+            PineSandbox.with_context("control-token mint timed out: #{e.message}", op: "POST #{PATH}")
+    rescue Faraday::ConnectionFailed => e
+      raise PineSandbox::ConnectionError,
+            PineSandbox.with_context("control-token mint connection failed: #{e.message}", op: "POST #{PATH}")
+    end
+
+    def apply_success(resp)
+      body = parse_json(resp)
+      token = body["token"]
+      raise ControlTokenError.new("mint response missing token", status: 200, body: resp.body, op: mint_op) if token.to_s.empty?
+
+      @token = token
+      @expires_at = compute_expiry(token, body)
+      @token
+    end
+
+    # The known op for every mint: POST the control-token endpoint. A 200-but-unusable
+    # response (missing token / bad expiry) still names WHICH portal call this was.
+    def mint_op
+      "POST #{PATH}"
+    end
+
+    # Prefer the token's own exp claim; fall back to response metadata only for
+    # older/non-JWT tests. A response with neither is unusable.
+    def compute_expiry(token, body)
+      token_exp = token_expiry(token)
+      return token_exp if token_exp
+
+      if body.key?("expires_in")
+        return @clock.call + body["expires_in"].to_i
+      elsif (abs = body["expires_at"])
+        begin
+          return Time.iso8601(abs.to_s)
+        rescue ArgumentError
+          raise ControlTokenError.new("mint response has an unparseable expires_at", status: 200, body: body, op: mint_op)
+        end
+      end
+      raise ControlTokenError.new("mint response missing expiry (expires_in / expires_at)", status: 200, body: body, op: mint_op)
+    end
+
+    def token_expiry(token)
+      parts = token.to_s.split(".")
+      return nil unless parts.length >= 2
+
+      payload = parts[1]
+      padding = "=" * ((4 - payload.length % 4) % 4)
+      claims = JSON.parse(Base64.urlsafe_decode64(payload + padding))
+      # A JWS payload should be a JSON object; anything else (a bare null/true/number) has
+      # no exp — fall back to the response expiry instead of raising NoMethodError on it.
+      return nil unless claims.is_a?(Hash)
+
+      raw = claims["exp"]
+      raw.nil? ? nil : Time.at(Integer(raw))
+    rescue ArgumentError, JSON::ParserError, TypeError
+      nil
+    end
+
+    # The jittered exponential backoff, capped, never shorter than Retry-After.
+    def backoff(attempt, retry_after)
+      [[0.2 * (2**(attempt - 1)) + @random.call * 0.1, MAX_BACKOFF_SECONDS].min, retry_after.to_f].max
+    end
+
+    # A Retry-After longer than the backoff cap: the server asks for a wait
+    # the mint won't make, so the caller gets the error and the wait.
+    def beyond_cap?(retry_after)
+      !retry_after.nil? && retry_after > MAX_BACKOFF_SECONDS
+    end
+
+    def parse_retry_after(resp)
+      raw = resp.headers["retry-after"] || resp.headers["Retry-After"]
+      return nil if raw.to_s.strip.empty?
+
+      seconds = Integer(raw)
+      seconds.positive? ? seconds : nil
+    rescue ArgumentError
+      nil # an HTTP-date Retry-After is allowed but rare here; fall back to backoff
+    end
+
+    def request_id(resp)
+      resp.headers["x-request-id"] || resp.headers["X-Request-Id"]
+    end
+
+    def error_message(resp, default)
+      body = parse_json(resp)
+      msg = body["message"] || body["error"]
+      msg.to_s.empty? ? default : msg.to_s
+    rescue StandardError
+      default
+    end
+
+    def parse_json(resp)
+      return resp.body if resp.body.is_a?(Hash)
+      return {} if resp.body.to_s.empty?
+
+      JSON.parse(resp.body)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def connection
+      @connection ||= Zone.faraday(scheme: @protocol, host: @host, gateway_url: @gateway_url) do |f|
+        f.options.open_timeout = @open_timeout
+        f.options.timeout = @request_timeout
+      end
+    end
+  end
+end

data/lib/pinesandbox/delegated_connection.rb

@@ -0,0 +1,46 @@
+module PineSandbox
+  # The browser-safe connection envelope — the ONLY thing a server hands a
+  # browser to drive a Computer's desktop. It carries NO `ct_`/`ps_`/project-JWS:
+  # only the data-plane base URL (`computer_host`, a full URI
+  # `https://<id>.computer.<zone>` so the web SDK derives the desktop ws/wss
+  # scheme from it), the visible session's name, the pinned spec major, and a
+  # freshly-minted, short-lived `dt_` desktop token (+ its expiry).
+  # Mirrors `DelegatedConnection` in the Computer API reference.
+  #
+  # `dt_` is a short-TTL connect ticket (re-minted per (re)connect) and view-scoped; drive is the control lease,
+  # not this token. Because the browser cannot mint a `dt_` (that needs `ct_`,
+  # server-held), the integrator re-mints server-side and refreshes the envelope
+  # before each (re)connect — the web SDK calls an integrator-supplied refresh
+  # callback on your server.
+  class DelegatedConnection
+    # The SDK's pinned Computer API major version. The web SDK pins the same
+    # major and fails fast on a mismatch.
+    SPEC_VERSION = 1
+
+    attr_reader :computer_host, :session_name, :spec_version, :desktop_token, :desktop_token_expires_at
+
+    def initialize(computer_host:, session_name:, desktop_token:, desktop_token_expires_at:,
+                   spec_version: SPEC_VERSION)
+      @computer_host = computer_host
+      @session_name = session_name
+      @spec_version = spec_version
+      @desktop_token = desktop_token
+      @desktop_token_expires_at = desktop_token_expires_at
+    end
+
+    # The wire shape the web SDK consumes. Session is reduced to its name —
+    # never the `Session` object (which holds the `ps_` token). The portal
+    # serializes this with `to_h` (the SDK stays framework-free); it may add its
+    # own scoped refresh endpoint to the payload before sending to the browser.
+    def to_h
+      {
+        computer_host: @computer_host,
+        session: { name: @session_name },
+        spec_version: @spec_version,
+        transports: {
+          desktop_token: { token: @desktop_token, expires_at: @desktop_token_expires_at }
+        }
+      }
+    end
+  end
+end