solana-ruby-kit 8.5.0 → 8.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3067fc0036448f0aef241f14f4e0b95f0faf6d6cedd4ed8aae5206d6e3169e28
-  data.tar.gz: a689c349c2e41d519b6e06814319d9760b2816bf59f48109d8d839790c4e6312
+  metadata.gz: 727cac096a118ea677195240a8ea3440f593b1f7930b0f0f603ae8156b66862a
+  data.tar.gz: e8a03418fa257b58b243933a9fe6c5918c7882f1bdfe47ad49f87bbd63a95a28
 SHA512:
-  metadata.gz: a02f7ce5743af32d1d6401f2023fc7293e33abfe1c0f495ec91f00a7ca4399e6fd654c7baa3f3c966ed34d6495514607432315323fb3425f294e8bf1713035ae
-  data.tar.gz: bfd06cf91f1fc1652cb5a578b822595c5f976537561fddbad22e04e6dc5567f1284b211b4e41be6472426005f3f4b0197c486fe5d87a046e2dac8989e30acb61
+  metadata.gz: 7fdcd2a35bde1be1eba49bf48f373d5bf701cd399c23f54f1bc53c4a7fdf8a21c4b3f478079be2a57095bd91aff7eb736a31fa047d357231bbcb3410bbaa6ad6
+  data.tar.gz: 890775283c250e98d91ab31263afd4b5c6f3fd093ae1c96422623d9c63716deb69a5376537b11811fd9deeb0961445d319f69086a985e41ee5d800d7f7bdb008

data/README.md

@@ -299,8 +299,54 @@ rescue Solana::Ruby::Kit::Rpc::RpcError => e
   puts e.message  # JSON-RPC error message
 rescue Solana::Ruby::Kit::Rpc::HttpTransportError => e
   puts e.status_code  # HTTP status code
+  puts e.retry_after  # raw Retry-After header, or nil
 ```
 
+#### Retries
+
+Transient failures are retried automatically, for every RPC method, with
+full-jitter exponential backoff. Defaults: `max_attempts: 5`, `base_delay: 0.25`,
+`max_delay: 8.0` (seconds). The wait before retry *n* is
+`rand * min(base_delay * 2**(n - 1), max_delay)`; a `Retry-After` header
+overrides it (still capped at `max_delay`).
+
+What gets retried depends on whether the request could have reached the node:
+
+| Failure | Retried for |
+|---|---|
+| Connect-phase: `Errno::ENETUNREACH`, `EHOSTUNREACH`, `ECONNREFUSED`, `Net::OpenTimeout`, `SocketError` | every method — the bytes never left the machine |
+| In-flight: `Errno::ECONNRESET`, `EPIPE`, `EOFError`, `Net::ReadTimeout`, `Net::WriteTimeout`, `OpenSSL::SSL::SSLError` | idempotent methods only |
+| HTTP 429 / 502 / 503 / 504 | idempotent methods only |
+| JSON-RPC error in a 200 response (`RpcError`) | never — the node answered |
+
+Every attempt resends the same bytes with the same JSON-RPC `id`; nothing is
+re-signed and no blockhash is refetched. Resending an identical signed
+`sendTransaction` is safe because the cluster dedupes by signature. When
+retries run out, the original error is re-raised.
+
+**`requestAirdrop` is not idempotent**: each accepted request is a new airdrop,
+so it is retried only on connect-phase errors. Add any of your own
+non-idempotent methods to `non_idempotent:`.
+
+```ruby
+# Customize, with logging
+policy = Solana::Ruby::Kit::Rpc::RetryPolicy.new(
+  max_attempts: 8,
+  max_delay:    15.0,
+  on_retry:     ->(method, attempt, error, wait) {
+    logger.warn("#{method} attempt #{attempt} failed (#{error.class}: #{error.message}); retrying in #{wait.round(2)}s")
+  }
+)
+rpc = Solana::Ruby::Kit::Rpc::Client.new(Solana::Ruby::Kit::RpcTypes.devnet, retry_policy: policy)
+
+# Disable
+rpc = Solana::Ruby::Kit::Rpc::Client.new(url, retry_policy: Solana::Ruby::Kit::Rpc::RetryPolicy.none)
+```
+
+`Rpc::Transport.new` takes the same `retry_policy:`, plus `sleeper:` (a
+callable receiving the wait in seconds, `Kernel.method(:sleep)` by default) so
+tests need not actually wait. The WebSocket subscriptions client is not covered.
+
 ### `Solana::Ruby::Kit::RpcTypes` — `@solana/rpc-types`
 
 Cluster URL helpers and typed wrappers.

data/lib/solana/ruby/kit/rpc/client.rb

@@ -80,18 +80,36 @@ module Solana::Ruby::Kit
       # @param cluster_url [RpcTypes::ClusterUrl, String]  endpoint to connect to.
       # @param headers     [Hash<String, String>]           additional HTTP headers.
       # @param timeout     [Integer]                        read timeout in seconds.
+      # @param retry_policy [RetryPolicy]                   transient-failure retries; `RetryPolicy.none` disables.
+      # @param sleeper     [#call]                          called with the wait in seconds between retries.
       sig do
         params(
           cluster_url:  T.untyped,    # RpcTypes::ClusterUrl or String
           headers:      T::Hash[String, String],
           timeout:      Integer,
-          open_timeout: Integer
+          open_timeout: Integer,
+          retry_policy: RetryPolicy,
+          sleeper:      T.any(Proc, Method)
         ).void
       end
-      def initialize(cluster_url, headers: {}, timeout: Transport::DEFAULT_TIMEOUT, open_timeout: Transport::DEFAULT_OPEN_TIMEOUT)
+      def initialize(
+        cluster_url,
+        headers:      {},
+        timeout:      Transport::DEFAULT_TIMEOUT,
+        open_timeout: Transport::DEFAULT_OPEN_TIMEOUT,
+        retry_policy: RetryPolicy.new,
+        sleeper:      Kernel.method(:sleep)
+      )
         url = cluster_url.respond_to?(:url) ? cluster_url.url : cluster_url.to_s
         @transport = T.let(
-          Transport.new(url: url, headers: headers, timeout: timeout, open_timeout: open_timeout),
+          Transport.new(
+            url:          url,
+            headers:      headers,
+            timeout:      timeout,
+            open_timeout: open_timeout,
+            retry_policy: retry_policy,
+            sleeper:      sleeper
+          ),
           Transport
         )
       end

data/lib/solana/ruby/kit/rpc/retry_policy.rb

@@ -0,0 +1,149 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'socket'
+require 'time'
+
+module Solana::Ruby::Kit
+  module Rpc
+    # Decides whether a failed JSON-RPC POST is retried, and how long to wait first.
+    # Ruby-only: upstream's `createHttpTransport` has no retry.
+    #
+    # Errors are classified by whether the request could have reached the node:
+    #
+    # - Connect-phase errors (`CONNECT_ERRORS`) are retried for every method — the
+    #   request bytes never left the machine, so nothing can have been executed twice.
+    # - In-flight errors (`IN_FLIGHT_ERRORS`) and HTTP 429/502/503/504 are retried
+    #   only for methods not listed in `non_idempotent`: the node may already have
+    #   acted on the request.
+    # - JSON-RPC error objects (`RpcError`) are never retried — the node answered.
+    #
+    # Backoff is full-jitter exponential: before retry n (1-based) the transport
+    # waits `rand * min(base_delay * 2**(n - 1), max_delay)`. A `Retry-After` header
+    # overrides it, capped at `max_delay`.
+    class RetryPolicy
+      extend T::Sig
+
+      CONNECT_ERRORS = T.let(
+        [Errno::ENETUNREACH, Errno::EHOSTUNREACH, Errno::ECONNREFUSED, Net::OpenTimeout, SocketError].freeze,
+        T::Array[T.class_of(Exception)]
+      )
+
+      IN_FLIGHT_ERRORS = T.let(
+        [Errno::ECONNRESET, Errno::EPIPE, EOFError, Net::ReadTimeout, Net::WriteTimeout, OpenSSL::SSL::SSLError].freeze,
+        T::Array[T.class_of(Exception)]
+      )
+
+      RETRYABLE_HTTP_STATUSES = T.let([429, 502, 503, 504].freeze, T::Array[Integer])
+
+      DEFAULT_NON_IDEMPOTENT = T.let(['requestAirdrop'].freeze, T::Array[String])
+
+      sig { returns(Integer) }
+      attr_reader :max_attempts
+
+      sig { returns(Float) }
+      attr_reader :base_delay
+
+      sig { returns(Float) }
+      attr_reader :max_delay
+
+      sig { returns(T::Array[String]) }
+      attr_reader :non_idempotent
+
+      # Called before each retry's sleep as `on_retry.call(method, attempt, error, wait)`,
+      # where `attempt` is the 1-based number of the attempt that just failed.
+      sig { returns(T.nilable(T.any(Proc, Method))) }
+      attr_reader :on_retry
+
+      # A policy that never retries.
+      sig { returns(RetryPolicy) }
+      def self.none
+        new(max_attempts: 1)
+      end
+
+      sig do
+        params(
+          max_attempts:   Integer,
+          base_delay:     Numeric,
+          max_delay:      Numeric,
+          non_idempotent: T::Array[String],
+          on_retry:       T.nilable(T.any(Proc, Method)),
+          random:         Random
+        ).void
+      end
+      def initialize(
+        max_attempts:   5,
+        base_delay:     0.25,
+        max_delay:      8.0,
+        non_idempotent: DEFAULT_NON_IDEMPOTENT,
+        on_retry:       nil,
+        random:         Random.new
+      )
+        raise ArgumentError, 'max_attempts must be at least 1' if max_attempts < 1
+
+        @max_attempts   = T.let(max_attempts, Integer)
+        @base_delay     = T.let(base_delay.to_f, Float)
+        @max_delay      = T.let(max_delay.to_f, Float)
+        @non_idempotent = T.let(non_idempotent.dup.freeze, T::Array[String])
+        @on_retry       = T.let(on_retry, T.nilable(T.any(Proc, Method)))
+        @random         = T.let(random, Random)
+      end
+
+      # Whether attempt number `attempt` (1-based) of `method`, having failed with
+      # `error`, should be followed by another.
+      sig { params(method: String, error: Exception, attempt: Integer).returns(T::Boolean) }
+      def retry?(method, error, attempt)
+        attempt < @max_attempts && retryable?(method, error)
+      end
+
+      # Whether `error` is retryable for `method` at all, ignoring the attempt budget.
+      sig { params(method: String, error: Exception).returns(T::Boolean) }
+      def retryable?(method, error)
+        return true if connect_error?(error)
+        return false unless idempotent?(method)
+
+        case error
+        when HttpTransportError then RETRYABLE_HTTP_STATUSES.include?(error.status_code)
+        else IN_FLIGHT_ERRORS.any? { |klass| error.is_a?(klass) }
+        end
+      end
+
+      sig { params(method: String).returns(T::Boolean) }
+      def idempotent?(method)
+        !@non_idempotent.include?(method)
+      end
+
+      # Seconds to wait after attempt number `attempt` (1-based) failed.
+      # `retry_after` is the raw `Retry-After` header value, if any: delta-seconds
+      # or an HTTP-date. An unparseable value falls back to the backoff.
+      sig { params(attempt: Integer, retry_after: T.nilable(String)).returns(Float) }
+      def delay(attempt, retry_after: nil)
+        server_wait = parse_retry_after(retry_after)
+        return [server_wait, @max_delay].min if server_wait
+
+        @random.rand(1.0) * [@base_delay * (2.0**(attempt - 1)), @max_delay].min
+      end
+
+      private
+
+      sig { params(error: Exception).returns(T::Boolean) }
+      def connect_error?(error)
+        CONNECT_ERRORS.any? { |klass| error.is_a?(klass) }
+      end
+
+      sig { params(value: T.nilable(String)).returns(T.nilable(Float)) }
+      def parse_retry_after(value)
+        return nil if value.nil?
+
+        stripped = value.strip
+        return [stripped.to_f, 0.0].max if stripped.match?(/\A\d+(\.\d+)?\z/)
+
+        [Time.httpdate(stripped) - Time.now, 0.0].max
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/solana/ruby/kit/rpc/transport.rb

@@ -5,6 +5,7 @@ require 'net/http'
 require 'json'
 require 'uri'
 require_relative '../errors'
+require_relative 'retry_policy'
 
 module Solana::Ruby::Kit
   module Rpc
@@ -33,9 +34,14 @@ module Solana::Ruby::Kit
       sig { returns(Integer) }
       attr_reader :status_code
 
-      sig { params(status_code: Integer, message: String).void }
-      def initialize(status_code, message)
+      # Raw `Retry-After` header value, when the response carried one.
+      sig { returns(T.nilable(String)) }
+      attr_reader :retry_after
+
+      sig { params(status_code: Integer, message: String, retry_after: T.nilable(String)).void }
+      def initialize(status_code, message, retry_after: nil)
         @status_code = T.let(status_code, Integer)
+        @retry_after = T.let(retry_after, T.nilable(String))
         super("HTTP #{status_code}: #{message}")
       end
     end
@@ -45,6 +51,14 @@ module Solana::Ruby::Kit
     #
     # Makes synchronous POST requests — TypeScript's async `fetch` maps to
     # Ruby's blocking `Net::HTTP`.  Use threads or Fibers for concurrency.
+    #
+    # Transient failures are retried according to `retry_policy` (see `RetryPolicy`;
+    # on by default, `RetryPolicy.none` disables it). The payload is built once, so
+    # every attempt sends the same bytes with the same JSON-RPC `id` — the transport
+    # never re-signs a transaction or refetches a blockhash.
+    #
+    # Each attempt opens its own connection (no keep-alive), so a Transport can be
+    # shared across threads and a retry never reuses a dead socket.
     class Transport
       extend T::Sig
 
@@ -61,7 +75,9 @@ module Solana::Ruby::Kit
           timeout:        Integer,
           open_timeout:   Integer,
           to_json:        T.nilable(T.proc.params(arg0: T.untyped).returns(String)),
-          from_json:      T.nilable(T.proc.params(arg0: String, arg1: T.untyped).returns(T.untyped))
+          from_json:      T.nilable(T.proc.params(arg0: String, arg1: T.untyped).returns(T.untyped)),
+          retry_policy:   RetryPolicy,
+          sleeper:        T.any(Proc, Method)
         ).void
       end
       def initialize(
@@ -70,7 +86,9 @@ module Solana::Ruby::Kit
         timeout:      DEFAULT_TIMEOUT,
         open_timeout: DEFAULT_OPEN_TIMEOUT,
         to_json:      nil,
-        from_json:    nil
+        from_json:    nil,
+        retry_policy: RetryPolicy.new,
+        sleeper:      Kernel.method(:sleep)
       )
         @url          = T.let(url, String)
         @headers      = T.let(headers, T::Hash[String, String])
@@ -80,8 +98,13 @@ module Solana::Ruby::Kit
         @from_json    = T.let(from_json, T.nilable(T.proc.params(arg0: String, arg1: T.untyped).returns(T.untyped)))
         @request_id   = T.let(0, Integer)
         @uri          = T.let(URI.parse(url), URI::Generic)
+        @retry_policy = T.let(retry_policy, RetryPolicy)
+        @sleeper      = T.let(sleeper, T.any(Proc, Method))
       end
 
+      sig { returns(RetryPolicy) }
+      attr_reader :retry_policy
+
       # Sends a single JSON-RPC request and returns the parsed `result`.
       # Raises `RpcError` on a JSON-RPC error, `HttpTransportError` on HTTP failure.
       sig { params(method: String, params: T::Array[T.untyped]).returns(T.untyped) }
@@ -89,7 +112,7 @@ module Solana::Ruby::Kit
         payload = build_payload(method, params)
         body    = @to_json ? @to_json.call(payload) : JSON.generate(payload)
 
-        response = post(body)
+        response = post_with_retry(method, body)
 
         parsed = @from_json ? @from_json.call(T.must(response.body), payload) : JSON.parse(T.must(response.body))
 
@@ -109,6 +132,32 @@ module Solana::Ruby::Kit
         { 'jsonrpc' => '2.0', 'id' => @request_id, 'method' => method, 'params' => params }
       end
 
+      # Posts `body` until it succeeds, the error is not retryable for `method`, or
+      # the policy's attempts run out — then re-raises the last error unchanged.
+      sig { params(method: String, body: String).returns(Net::HTTPResponse) }
+      def post_with_retry(method, body)
+        attempt = 0
+        begin
+          attempt += 1
+          post(body)
+        rescue StandardError => e
+          reset_connection unless e.is_a?(HttpTransportError)
+          raise unless @retry_policy.retry?(method, e, attempt)
+
+          retry_after = e.is_a?(HttpTransportError) ? e.retry_after : nil
+          wait = @retry_policy.delay(attempt, retry_after: retry_after)
+          @retry_policy.on_retry&.call(method, attempt, e, wait)
+          @sleeper.call(wait)
+          retry
+        end
+      end
+
+      # Called after every socket-level error, before any retry. Nothing to do
+      # while each attempt opens a fresh `Net::HTTP`; a keep-alive connection
+      # would be closed here so the retry could not reuse a dead socket.
+      sig { void }
+      def reset_connection; end
+
       sig { params(body: String).returns(Net::HTTPResponse) }
       def post(body)
         http = Net::HTTP.new(@uri.host, @uri.port)
@@ -126,7 +175,7 @@ module Solana::Ruby::Kit
         response = http.request(req)
 
         unless response.is_a?(Net::HTTPSuccess)
-          raise HttpTransportError.new(response.code.to_i, response.message)
+          raise HttpTransportError.new(response.code.to_i, response.message, retry_after: response['Retry-After'])
         end
 
         response

data/lib/solana/ruby/kit/version.rb

@@ -4,7 +4,7 @@
 module Solana
   module Ruby
     module Kit
-      VERSION = '8.5.0'
+      VERSION = '8.5.1'
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solana-ruby-kit
 version: !ruby/object:Gem::Version
-  version: 8.5.0
+  version: 8.5.1
 platform: ruby
 authors:
 - Paul Zupan, Idhra Inc.
@@ -289,6 +289,7 @@ files:
 - lib/solana/ruby/kit/rpc/api/send_transaction.rb
 - lib/solana/ruby/kit/rpc/api/simulate_transaction.rb
 - lib/solana/ruby/kit/rpc/client.rb
+- lib/solana/ruby/kit/rpc/retry_policy.rb
 - lib/solana/ruby/kit/rpc/transport.rb
 - lib/solana/ruby/kit/rpc_parsed_types.rb
 - lib/solana/ruby/kit/rpc_parsed_types/address_lookup_table.rb