solana-studio 0.12.0 → 0.12.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a067bc88c6dbfae4cd19a6a0132c0c54864e20e2c405211d935b91d134855111
-  data.tar.gz: 2c15956cee0c63082e85dd73f53c601b2f7c5fac5ec6e455830225e649ca8a2a
+  metadata.gz: 14ad71141b369bcdc3c22aad7644fca987cf924efd8aab247b753ba76a52dad3
+  data.tar.gz: 41c9eb34aecfb9e4c6d5ef6847f64928374549b3859a4ebd0a999e37e4c4188d
 SHA512:
-  metadata.gz: 8788bdff89c7b8d0d80d22fe2159c97e49d9955e573dcb41ec4667361ab05e354ca8ff30227a6de4bbf904e79682d309aeeef9c868d720c83850e42824d14706
-  data.tar.gz: f77ab0deb992f4105085f5ddfb3eb2267c52c6b2373c2eba81401369553fc5b6803fbad70e345761190f7c10ed05d88b413338afc3c7d678109abb334e6cff17
+  metadata.gz: 5f27e7398fcc671ef3d1c8e32ab1a43b5fa9044d957b95cfe1c4bb1c9e7e5267e9870a28f07d1e3ba2a7b8b70603dd15d9b9d64798c11da7a80f893d5bbdbee4
+  data.tar.gz: 6032788536e6174d5b8fb3ee9ddd0e06888ea8b07d9f63305fe947d261e9f36962ea2b288d06b4c9e6718bf463f9bbf436d77707ed0d485e5240d689273aa6ad

data/CHANGELOG.md

@@ -4,6 +4,21 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 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
+- **Development bundle: studio-engine floor raised to 0.81.1** (`Gemfile`). 0.81.1 declares `redis < 6`; the old `~> 0.57` let a lock that already held redis 6.0.0 keep studio-engine at 0.81.0 under a conservative update. Development and test only; the gem's runtime dependencies are unchanged.
+
 ## v0.12.0 (2026-09-17)
 
 ### Fixed

data/lib/solana/client.rb

@@ -2,6 +2,7 @@ require "net/http"
 require "json"
 require "uri"
 require "openssl"
+require "time"
 
 module Solana
   class Client
@@ -13,10 +14,31 @@ module Solana
       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
+    # 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"
 
@@ -181,32 +203,99 @@ module Solana
       retries = 0
       begin
         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
+        # 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
+          sleep retry_delay(retries, response)
           retry
         end
         raise
       rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET => e
         if retries < MAX_RETRIES
           retries += 1
-          sleep RETRY_DELAY * retries
+          sleep retry_delay(retries)
           retry
         end
         raise RpcError.new("Network error: #{e.message}")
       end
     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 +324,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.0"
+  VERSION = "0.12.2"
 end

metadata

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