solana-studio 0.12.1 → 0.12.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26e0e9024da086eab6ef2c5039a616d92e33d3a0857db9709ed6456dcfd2b1c8
-  data.tar.gz: 3a5284d8b9bce6ac1d5b9e6529557b7fff289719bf004c2d86755ec88d3b7b0d
+  metadata.gz: 4b9393d6e5a4017b9cee63d30fcab9d19f701a7df0aa199c8f69ed88884c1efc
+  data.tar.gz: dec190556084d5b8e87b47d261d16b1bb8cb476bb56b2d89b2e51dca1b87759f
 SHA512:
-  metadata.gz: b8ef4516331e8835754767b457a5309bb04909aa9c02c1564342d29080cdad6f4791c1a8b1fb9b0233321ca1cf3e45937bfe7563b0d68ce58e315ecaf1738911
-  data.tar.gz: 6b61d94b2e4892e2412fbff5afb4675f3d553e1de9b68d5f6ed2a3013d0a0de3849bd979596f4a16d9905b1391c62b01acc44412c14bbf8a4e7ffab34405260c
+  metadata.gz: 334a207a8a10c6836708f642e5b62f77bc379aad03c748d6ca4d99b2c44744ccdf7ce5cfd8abb6e5138c49f1a66a60cab6866f80d3c39e62dc4cf847c6d0deee
+  data.tar.gz: eba72988237606e308db17446adc229fd9b77bf179684814bd1d0d3665e46e6287aec63af2848eb5105c6f4ef6afe7e78e12471af2b65ef618985e36b032101f

data/CHANGELOG.md

@@ -4,6 +4,28 @@ 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
+- **`Solana::Client#call` reads the HTTP status before it parses the body, and retries a plain-text 429** (`lib/solana/client.rb`). Helius answers a rate limit with HTTP 429 and the plain-text body `Too many requests`. The client parsed every body as JSON first, so that answer raised `JSON::ParserError`, which `#call` did not rescue, and the read was never retried: `retryable_error?` only matched a JSON-RPC error `code` 429. On 2026-10-06 this failed 7 of contest 232's reads in turf-monster's production wallet backfill, and every mainnet read (settle and grading included) had the same exposure. Now HTTP 429, 500, 502, 503 and 504 (`RETRYABLE_HTTP_STATUSES`) are retried within the existing budget (`MAX_RETRIES` = 3 retries, linear `RETRY_DELAY` backoff), waiting for `Retry-After` when the server sends one (seconds or an HTTP-date, capped at `MAX_RETRY_AFTER` = 10s), with up to half a `RETRY_DELAY` of jitter on every wait, network retries included. When the retries run out, the client raises the new `Solana::Client::HttpError`, a subclass of `RpcError` whose `code` (and `status`) is the HTTP status, so `rescue RpcError` and `e.code == 429` keep working. Any other non-2xx raises at once without a retry; when its body carries a JSON-RPC error, that error's code and message are raised as before. A body that is not JSON raises `HttpError`, never `JSON::ParserError`; the body excerpt in its message is scrubbed to valid UTF-8, so a Latin-1 or gzip error page cannot raise `Encoding::CompatibilityError` where a host prints the message; and a non-2xx JSON body with no `error` key raises rather than returning a `nil` result that reads as "account not found". A transport that reports no status (a host's test stub of `#http_post` answering `#body` only) is parsed exactly as before. `sendTransaction` is now also retried on a 5xx; like a read timeout, that re-posts the same signed wire, which the cluster deduplicates by signature, and `Solana::Cosign` already treats every send-time error as possibly landed.
+
+### Tests
+- **`test/client_http_status_test.rb` (22, new)**: a plain-text 429 then a JSON result returns the result; a 429 on every attempt raises `RpcError` code 429 after exactly `MAX_RETRIES` + 1 attempts; backoff, jitter, `Retry-After` in seconds and as an HTTP-date, its cap and an unreadable value; a JSON-RPC 429 inside HTTP 200 still retries; a 503 then success, a 502 to exhaustion, a 503 `Retry-After`, a 500 carrying a JSON-RPC error retried on its status; a 400 and a 401 raise once without a retry; a JSON-RPC error on a 400 keeps its code; a 404 JSON body without an error raises; a non-JSON 200 raises `RpcError`; a long body is truncated; a Latin-1 or gzip body yields a UTF-8 message a host can interpolate; a status-less transport stub still parses. A control asserts the plain-text body raises `JSON::ParserError`, the exception the old parse-first code let escape. Run against the unfixed client, 19 of the 22 fail (`JSON::ParserError` or the missing `HttpError`).
+- **10 mutants against the new code, all 10 KILLED**, each reverted after: the UTF-8 scrub of the body excerpt, the status-first check, the HTTP branch of `retryable_error?`, `Retry-After`, its cap, the jitter, 400/401 made retryable, 5xx made non-retryable, the non-2xx raise, and `JSON::ParserError` let through. Two survived the first run (the status-first check and the non-2xx raise); the 500-with-JSON-RPC-error and 404-JSON tests were added and both are now killed.
+- **Consumer run: turf-monster's 134 Solana-touching test files (1,761 runs) against this tree** (`gem "solana-studio", path:` in a desk, not committed). The run found the binary-body defect above: two `solana_network_alignment_test.rb` cases (a Latin-1 page, a gzip body) raised `Encoding::CompatibilityError`. It also found that `solana_health_unauthorized_rpc_test.rb` asserted the old `JSON::ParserError` name; turf-monster's sibling PR widens that assertion so it holds on either side of the lock bump.
+
 ## v0.12.1 (2026-09-30)
 
 ### Changed

data/lib/solana/client.rb

@@ -2,32 +2,127 @@ require "net/http"
 require "json"
 require "uri"
 require "openssl"
+require "time"
 
 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)
       end
     end
 
+    # An answer whose HTTP status, not a JSON-RPC error, says the call failed:
+    # a 429 or 5xx after the retries ran out, any other non-2xx without a
+    # JSON-RPC error in its body, or a body that is not JSON at all. `code` is
+    # the HTTP status, so a caller's `rescue RpcError` and `e.code == 429` keep
+    # working; `status` says the same thing by name.
+    class HttpError < RpcError
+      alias status code
+    end
+
     class InsecureRpcUrlError < ArgumentError; end
 
     MAX_RETRIES = 3
     RETRY_DELAY = 1 # seconds
+    # A server's Retry-After is honoured up to this many seconds. Reads run
+    # inside requests and jobs; a provider asking for a minute gets the cap,
+    # and the retry budget then decides.
+    MAX_RETRY_AFTER = 10
+    # 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
+    # How much of an unparseable body an error message carries.
+    BODY_EXCERPT = 200
 
     DEFAULT_RPC_URL = "https://api.devnet.solana.com"
 
     # 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)
@@ -178,35 +273,141 @@ 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)
-        parsed = JSON.parse(response.body)
+        status = http_status(response)
+        # The status first: a rate limit or gateway failure often carries a
+        # body that is not JSON (Helius answers 429 with "Too many requests").
+        raise http_error(status, response) if RETRYABLE_HTTP_STATUSES.include?(status)
 
-        if parsed["error"]
+        parsed = parse_body(response, status)
+
+        if parsed.is_a?(Hash) && parsed["error"]
           error = parsed["error"]
           raise RpcError.new(error["message"], code: error["code"])
         end
+        raise http_error(status, response) if status && !(200..299).cover?(status)
 
         parsed["result"]
       rescue RpcError => e
-        # Retry on rate limit (429) or blockhash expiry
-        if retries < MAX_RETRIES && retryable_error?(e)
-          retries += 1
-          sleep RETRY_DELAY * retries
-          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
+    # exactly as before.
+    def http_status(response)
+      return nil unless response.respond_to?(:code)
+
+      Integer(response.code.to_s, 10)
+    rescue ArgumentError
+      nil
+    end
+
+    # JSON.parse, except that a body which is not JSON raises HttpError (an
+    # RpcError) carrying the status, never JSON::ParserError.
+    def parse_body(response, status)
+      JSON.parse(response.body.to_s)
+    rescue JSON::ParserError
+      raise HttpError.new("RPC response is not JSON (HTTP #{status || 'status unknown'}): #{excerpt(response)}",
+                          code: status)
+    end
+
+    def http_error(status, response)
+      HttpError.new("HTTP #{status} from RPC: #{excerpt(response)}", code: status)
+    end
+
+    # The start of the body, safe to interpolate: an upstream error page can be
+    # Latin-1 or gzip bytes (Net::HTTP hands those back as ASCII-8BIT), and
+    # mixing them into a UTF-8 message raises Encoding::CompatibilityError.
+    def excerpt(response)
+      text = response.body.to_s.dup.force_encoding(Encoding::UTF_8).scrub("?").strip
+      text.length > BODY_EXCERPT ? "#{text[0, BODY_EXCERPT]}…" : text
+    end
+
+    # The wait before retry number `attempt`: the linear backoff (1s, 2s, 3s at
+    # RETRY_DELAY = 1), or the server's Retry-After when it asks for longer,
+    # plus jitter.
+    def retry_delay(attempt, response = nil)
+      base = RETRY_DELAY * attempt
+      asked = retry_after_seconds(response)
+      base = asked if asked && asked > base
+      base + (rand * RETRY_DELAY * RETRY_JITTER)
+    end
+
+    # Retry-After as seconds (RFC 9110: delay-seconds or an HTTP-date), capped
+    # at MAX_RETRY_AFTER. nil when absent or unreadable.
+    def retry_after_seconds(response)
+      return nil unless response.respond_to?(:[])
+
+      value = response["Retry-After"].to_s.strip
+      return nil if value.empty?
+
+      seconds = if value.match?(/\A\d+\z/)
+                  value.to_i
+                else
+                  Time.httpdate(value) - Time.now
+                end
+      seconds.clamp(0, MAX_RETRY_AFTER)
+    rescue ArgumentError
+      nil
+    end
+
     def http_post(body)
       http = Net::HTTP.new(@uri.host, @uri.port)
       if @uri.scheme == "https"
@@ -235,7 +436,8 @@ module Solana
     end
 
     def retryable_error?(error)
-      return true if error.code == 429 # rate limited
+      return RETRYABLE_HTTP_STATUSES.include?(error.code) if error.is_a?(HttpError)
+      return true if error.code == 429 # JSON-RPC rate limited
       return true if error.message.include?("Blockhash not found")
       false
     end

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.1"
+  VERSION = "0.12.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solana-studio
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.12.3
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ed25519