solana-studio 0.12.2 → 0.12.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14ad71141b369bcdc3c22aad7644fca987cf924efd8aab247b753ba76a52dad3
-  data.tar.gz: 41c9eb34aecfb9e4c6d5ef6847f64928374549b3859a4ebd0a999e37e4c4188d
+  metadata.gz: 4b9393d6e5a4017b9cee63d30fcab9d19f701a7df0aa199c8f69ed88884c1efc
+  data.tar.gz: dec190556084d5b8e87b47d261d16b1bb8cb476bb56b2d89b2e51dca1b87759f
 SHA512:
-  metadata.gz: 5f27e7398fcc671ef3d1c8e32ab1a43b5fa9044d957b95cfe1c4bb1c9e7e5267e9870a28f07d1e3ba2a7b8b70603dd15d9b9d64798c11da7a80f893d5bbdbee4
-  data.tar.gz: 6032788536e6174d5b8fb3ee9ddd0e06888ea8b07d9f63305fe947d261e9f36962ea2b288d06b4c9e6718bf463f9bbf436d77707ed0d485e5240d689273aa6ad
+  metadata.gz: 334a207a8a10c6836708f642e5b62f77bc379aad03c748d6ca4d99b2c44744ccdf7ce5cfd8abb6e5138c49f1a66a60cab6866f80d3c39e62dc4cf847c6d0deee
+  data.tar.gz: eba72988237606e308db17446adc229fd9b77bf179684814bd1d0d3665e46e6287aec63af2848eb5105c6f4ef6afe7e78e12471af2b65ef618985e36b032101f

data/CHANGELOG.md

@@ -4,6 +4,18 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## v0.12.3 (2026-10-07)
+
+### Fixed
+- **`Solana::Client#call` has a total-wait budget, so one call can no longer sleep past a web request's timeout** (`lib/solana/client.rb`). The 429/5xx retry shipped in 0.12.2 honours `Retry-After` up to 10s, three times, plus jitter: about 31.5s of sleeping in one call, past Heroku's 30s request timeout on the turf-monster paths that call Solana inside a request. Now a call sums its waits and, when the next wait would carry that sum past its budget, raises its last error at once instead of sleeping; it never sleeps part of a wait. A `Retry-After` larger than what is left raises straight away. The budget is `DEFAULT_WAIT_BUDGET` = 15s, set per client with `Solana::Client.new(wait_budget:)` and per call with `Solana::Client.with_wait_budget(seconds) { ... }`, which applies to every call the current thread makes inside the block, restores the outer budget when it ends, and must be opened inside a `Thread.new` body to reach it. It bounds the waits between attempts only, not each attempt's time on the wire (`open_timeout` 10s, `read_timeout` 30s are unchanged). Network-error retries share the same budget. Linear backoff alone (1s + 2s + 3s) fits the default, so ordinary retries are unchanged.
+
+### Added
+- **Retries are visible** (`lib/solana/client.rb`). Every `#call` records a `Solana::Client::CallStats` (method, attempts, retries, seconds waited, budget, and whether the budget stopped it), readable from `Client#last_call_stats` after the call returns or raises (scoped to that client and that thread, so a prepended wrapper such as turf-monster's `Solana::ClientLogger` can read it after `super`), and from the new `RpcError#call_stats` on any error `#call` raises. Each retry, and a budget stop, writes one `warn` line to `Solana::Client.logger` (Rails.logger in a Rails host, nothing elsewhere; a client's own `logger:` wins) naming the method, the retry count, the wait, the total waited and the budget, never the RPC URL or a param. A logger that raises does not change what `#call` returns.
+
+### Tests
+- **`test/client_wait_budget_test.rb` (19, new)**: the default budget stops a `Retry-After: 10` call after one 10.5s wait; linear backoff inside the budget still gets all three retries and succeeds; a per-client budget, a zero budget, and `with_wait_budget` (overrides, nests, restores on raise, refuses a bad value without clobbering the outer one); network retries share the budget; a `Retry-After` larger than the remaining budget raises without sleeping, at the first wait or after earlier ones; each retry and the budget stop are logged with the retry count and the total waited, never the URL, key or params; a raising logger is harmless; a module prepended over `#call` in turf's `ClientLogger` shape reads the retry count and time waited on success and on failure; `last_call_stats` is per client; and a `sendTransaction` retried through a 429 and a 503 posts byte-identical bodies, captured at `Net::HTTP#request`. The control lifts the budget (`Float::INFINITY`) and shows the same script sleeping 31.5s, past 30s.
+- **13 mutants against the new code, 12 KILLED**, each reverted after: the budget check removed, `>` made `>=`, the next delay left out of the check, the waited sum not accumulated, the retry count not incremented (loops forever; killed by timeout), the thread-local override ignored, the outer budget not restored, the log line dropped, `call_stats` not attached to the error, `last_call_stats` not scoped to its client, the logger rescue removed, and validation moved after the override is cleared. The survivor was an explicit NaN check, equivalent to `seconds >= 0` (NaN fails it), so the check was removed.
+
 ## v0.12.2 (2026-10-07)
 
 ### Fixed

data/lib/solana/client.rb

@@ -8,6 +8,9 @@ module Solana
   class Client
     class RpcError < StandardError
       attr_reader :code
+      # The CallStats of the #call that raised this error (retries, seconds
+      # waited, the budget), or nil when the error never left #call.
+      attr_accessor :call_stats
       def initialize(message, code: nil)
         @code = code
         super(message)
@@ -34,6 +37,18 @@ module Solana
     # Up to this fraction of RETRY_DELAY is added to every wait, so callers
     # throttled together do not all come back on the same tick.
     RETRY_JITTER = 0.5
+    # The most seconds one #call may spend SLEEPING between attempts, summed
+    # over every retry. MAX_RETRIES Retry-After waits at the cap come to about
+    # 31.5s, past Heroku's 30s request timeout, so a call stops and raises its
+    # last error rather than start a wait that would cross this line. It bounds
+    # the waits only, not the time each attempt spends on the wire (see
+    # #http_post's open and read timeouts). Set per client with
+    # `Client.new(wait_budget:)`, or per call with `Client.with_wait_budget`.
+    DEFAULT_WAIT_BUDGET = 15.0
+    # What one #call did: how many attempts and retries it made, the seconds it
+    # slept, the budget it ran under, and whether that budget is what stopped
+    # it. Read it from Client#last_call_stats, or from RpcError#call_stats.
+    CallStats = Struct.new(:method, :attempts, :retries, :waited, :budget, :budget_stopped, keyword_init: true)
     # HTTP statuses that mean "not processed, ask again": rate limited, or the
     # provider or a gateway in front of it failed.
     RETRYABLE_HTTP_STATUSES = [429, 500, 502, 503, 504].freeze
@@ -45,11 +60,69 @@ module Solana
     # Hostnames where plain http:// is permitted (local testing only).
     HTTP_OK_HOSTS = %w[localhost 127.0.0.1 ::1 0.0.0.0].freeze
 
-    def initialize(rpc_url: nil)
+    # The thread-local key for Client.with_wait_budget, and for the stats of
+    # the last #call this thread made.
+    WAIT_BUDGET_KEY = :solana_client_wait_budget
+    LAST_CALL_KEY = :solana_client_last_call
+
+    class << self
+      # Where #call writes one line per retry. Defaults to Rails.logger in a
+      # Rails host and to nothing elsewhere; a client's own `logger:` wins.
+      attr_writer :logger
+
+      def logger
+        return @logger if defined?(@logger)
+
+        Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
+      end
+
+      # Every #call made by THIS thread (any client) inside the block runs
+      # under `seconds` of total wait instead of its client's budget. For a
+      # caller inside a web request:
+      #
+      #   Solana::Client.with_wait_budget(4) { vault.fetch_wallet_balances(addr) }
+      #
+      # Thread-scoped, so a Thread.new body must open its own block. Nesting
+      # restores the outer budget when the inner block ends.
+      def with_wait_budget(seconds)
+        seconds = validate_wait_budget!(seconds)
+        previous = Thread.current[WAIT_BUDGET_KEY]
+        begin
+          Thread.current[WAIT_BUDGET_KEY] = seconds
+          yield
+        ensure
+          Thread.current[WAIT_BUDGET_KEY] = previous
+        end
+      end
+
+      def validate_wait_budget!(seconds)
+        # NaN fails `>= 0`, so it is refused with the negatives.
+        unless seconds.is_a?(Numeric) && seconds >= 0
+          raise ArgumentError, "wait_budget must be a non-negative number of seconds (got #{seconds.inspect})"
+        end
+
+        seconds.to_f
+      end
+    end
+
+    attr_reader :wait_budget
+
+    def initialize(rpc_url: nil, wait_budget: DEFAULT_WAIT_BUDGET, logger: nil)
       @rpc_url = rpc_url || ENV.fetch("SOLANA_RPC_URL", DEFAULT_RPC_URL)
       @uri = URI.parse(@rpc_url)
       validate_rpc_scheme!
       @request_id = 0
+      @wait_budget = self.class.validate_wait_budget!(wait_budget)
+      @logger = logger
+    end
+
+    # The CallStats of the last #call THIS client made on THIS thread, or nil.
+    # Thread-scoped because one client is shared by request threads. A wrapper
+    # prepended over #call (turf-monster's Solana::ClientLogger) reads it after
+    # `super` returns or raises.
+    def last_call_stats
+      stats = Thread.current[LAST_CALL_KEY]
+      stats[:stats] if stats && stats[:client].equal?(self)
     end
 
     def get_account_info(pubkey, encoding: "base64", commitment: nil)
@@ -200,8 +273,12 @@ module Solana
         params: params
       }
 
-      retries = 0
+      budget = Thread.current[WAIT_BUDGET_KEY] || @wait_budget
+      stats = CallStats.new(method: method.to_s, attempts: 0, retries: 0, waited: 0.0,
+                            budget: budget, budget_stopped: false)
+      Thread.current[LAST_CALL_KEY] = { client: self, stats: stats }
       begin
+        stats.attempts += 1
         response = http_post(body)
         status = http_status(response)
         # The status first: a rate limit or gateway failure often carries a
@@ -218,23 +295,58 @@ module Solana
 
         parsed["result"]
       rescue RpcError => e
-        # Retry an HTTP 429/5xx, a JSON-RPC rate limit, or blockhash expiry.
-        if retries < MAX_RETRIES && retryable_error?(e)
-          retries += 1
-          sleep retry_delay(retries, response)
-          retry
-        end
+        # Retry an HTTP 429/5xx, a JSON-RPC rate limit, or blockhash expiry,
+        # while the wait fits the budget.
+        retry if stats.retries < MAX_RETRIES && retryable_error?(e) &&
+                 wait_for_retry(stats, retry_delay(stats.retries + 1, response), e)
+        e.call_stats = stats
         raise
       rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET => e
-        if retries < MAX_RETRIES
-          retries += 1
-          sleep retry_delay(retries)
-          retry
-        end
-        raise RpcError.new("Network error: #{e.message}")
+        retry if stats.retries < MAX_RETRIES && wait_for_retry(stats, retry_delay(stats.retries + 1), e)
+        error = RpcError.new("Network error: #{e.message}")
+        error.call_stats = stats
+        raise error
       end
     end
 
+    # Sleep `delay` before the next attempt and return true, or, when that
+    # sleep would carry the call's total wait past its budget, mark the stats
+    # and return false so the caller raises its last error now. Never sleeps
+    # part of a wait: a retry that cannot have its full delay is not made.
+    def wait_for_retry(stats, delay, error)
+      if stats.waited + delay > stats.budget
+        stats.budget_stopped = true
+        log_retry("stopped", stats, delay, error)
+        return false
+      end
+
+      stats.retries += 1
+      log_retry("retry", stats, delay, error)
+      sleep delay
+      stats.waited += delay
+      true
+    end
+
+    # One line per retry, and one when the budget stops a call. It names the
+    # method, the cause and the numbers only: never the RPC URL, which can
+    # carry an API key on its query string, and never a request param.
+    def log_retry(event, stats, delay, error)
+      logger = @logger || self.class.logger
+      return unless logger
+
+      cause = error.is_a?(RpcError) ? "#{error.class.name.split('::').last} #{error.code}" : error.class.name
+      line = if event == "retry"
+               format("[Solana::Client] %s retry %d/%d after %s: waiting %.2fs (%.2fs of %.2fs budget)",
+                      stats.method, stats.retries, MAX_RETRIES, cause, delay, stats.waited + delay, stats.budget)
+             else
+               format("[Solana::Client] %s wait budget spent after %d retries (%.2fs waited, next wait %.2fs, budget %.2fs): raising %s",
+                      stats.method, stats.retries, stats.waited, delay, stats.budget, cause)
+             end
+      logger.warn(line)
+    rescue StandardError
+      nil # a broken logger never changes what #call returns or raises
+    end
+
     # The response's HTTP status as an Integer, or nil when the transport does
     # not report one. A real Net::HTTPResponse always does; host test suites
     # stub #http_post with objects that answer #body only, and those are read

data/lib/solana_studio/version.rb

@@ -16,5 +16,5 @@ module SolanaStudio
   # through the normal cycle. Splitting the version out is the same shape
   # studio-engine already uses (lib/studio/version.rb) and hands each file back
   # to its real owner: this one to the release, the gemspec to the PR.
-  VERSION = "0.12.2"
+  VERSION = "0.12.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solana-studio
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.12.3
 platform: ruby
 authors:
 - Alex McRitchie