block_given 0.1.0 → 0.2.0

data/lib/block_given/connectors/alchemy.rb

@@ -2,13 +2,34 @@
 
 module BlockGiven
   module Connectors
-    # Alchemy JSON-RPC connector. The endpoint is derived from the chain, so one
-    # connector instance can serve any Alchemy-supported network.
+    # Alchemy JSON-RPC connector, an {Http} transport whose endpoint is derived from the chain.
     #
-    #   BlockGiven::Connectors::Alchemy.new(api_key: ENV["ALCHEMY_API_KEY"])
+    # The URL is `https://<chain.alchemy_network>.g.alchemy.com/v2/<api_key>`, so a single instance can
+    # serve every Alchemy-supported network declared in {Chains} (`alchemy_network` set). Retries, backoff,
+    # timeouts and headers behave exactly as in {Http}.
+    #
+    # The API key never leaks: {#inspect} shows only its first 4 characters and {#redact} strips it from any
+    # endpoint that ends up in a log line or an error message.
+    #
+    # @example
+    #   connector = BlockGiven::Connectors::Alchemy.new(api_key: ENV["ALCHEMY_API_KEY"])
+    #   BlockGiven::Client.new(chain: :base, connector: connector).block_number
+    #   connector.inspect # => "#<BlockGiven::Connectors::Alchemy api_key=abcd…>"
     class Alchemy < Http
+      # @!attribute [r] api_key
+      #   @return [String] the Alchemy API key (as a String); do not log it, use {#inspect} or {#redact}
+
       attr_reader :api_key
 
+      # Builds an Alchemy transport. There is no `url:` argument: the endpoint is computed per chain.
+      #
+      # @param api_key [String, #to_s] Alchemy API key
+      # @param timeout [Numeric] seconds for the open, read and write timeouts of each HTTP request
+      # @param retries [Integer] number of retries after the first failed attempt
+      # @param retry_delay [Numeric] seconds slept before the first retry; doubled on each further retry
+      # @param logger [Logger, nil] receives retry notices at debug level. Defaults to `BlockGiven.config.logger`.
+      # @param headers [Hash{String => String}] extra headers merged over the {Http} defaults
+      # @raise [ConfigurationError] when `api_key` is nil or empty
       def initialize(api_key:, timeout: 30, retries: 3, retry_delay: 0.5, logger: nil, headers: {})
         raise ConfigurationError, "Alchemy api_key is required" if api_key.nil? || api_key.to_s.empty?
 
@@ -16,6 +37,11 @@ module BlockGiven
         super(url: nil, headers: headers, timeout: timeout, retries: retries, retry_delay: retry_delay, logger: logger)
       end
 
+      # Alchemy endpoint for a chain: `https://<alchemy_network>.g.alchemy.com/v2/<api_key>`.
+      #
+      # @param chain [Chain] chain being queried; its `alchemy_network` (e.g. `"base-mainnet"`) selects the host
+      # @return [String] the full endpoint URL, including the API key
+      # @raise [ConfigurationError] when `chain` is nil or has no `alchemy_network`
       def endpoint(chain)
         raise ConfigurationError, "Alchemy connector needs a chain" if chain.nil?
         raise ConfigurationError, "#{chain.name} is not available on Alchemy" unless chain.alchemy_network
@@ -23,9 +49,17 @@ module BlockGiven
         "https://#{chain.alchemy_network}.g.alchemy.com/v2/#{api_key}"
       end
 
+      # Short description with the API key masked (first 4 characters followed by an ellipsis).
+      #
+      # @return [String] e.g. `"#<BlockGiven::Connectors::Alchemy api_key=abcd…>"`
       def inspect = "#<BlockGiven::Connectors::Alchemy api_key=#{redacted_key}>"
 
-      # Keeps the network host visible, masks the key: https://base-mainnet.g.alchemy.com/v2/abcd…
+      # Masks the API key inside an endpoint while keeping the network host visible.
+      #
+      # @example
+      #   connector.redact(connector.endpoint(chain)) # => "https://base-mainnet.g.alchemy.com/v2/abcd…"
+      # @param endpoint [String, #to_s] URL possibly containing the API key
+      # @return [String] the URL with every occurrence of the key replaced by its masked form
       def redact(endpoint) = endpoint.to_s.sub(api_key, redacted_key)
 
       private

data/lib/block_given/connectors/base.rb

@@ -1,17 +1,41 @@
 # frozen_string_literal: true
 
 module BlockGiven
+  # JSON-RPC transports: {Connectors::Base} defines the interface, {Connectors::Http} speaks JSON-RPC over HTTP(S),
+  # {Connectors::Alchemy} derives Alchemy endpoints from the chain and {Connectors::Stub} serves canned responses
+  # in tests. A connector is set globally with `BlockGiven.config.connector` or passed to {Client#initialize}.
   module Connectors
-    # A connector is a JSON-RPC transport. Subclasses implement #request; the
-    # chain is passed so multi-network providers (Alchemy) can pick the endpoint.
+    # Abstract JSON-RPC transport every connector derives from.
+    #
+    # A connector only knows how to send a JSON-RPC method with its params and hand back the `result`.
+    # The {Chain} is passed on each call so that multi-network providers ({Alchemy}) can derive the endpoint
+    # from it; single-endpoint transports ({Http} with an explicit `url:`) may ignore it. Concrete
+    # connectors: {Http}, {Alchemy} and, for tests, {Stub}.
+    #
+    # @abstract Subclass and override {#request}; override {#batch} when the transport supports real batching.
     class Base
-      # @return the JSON-RPC `result` (raw JSON value). Raises BlockGiven::RpcError on error.
+      # Sends one JSON-RPC request and returns its `result`.
+      #
+      # @abstract
+      # @param method [String] JSON-RPC method name, e.g. `"eth_blockNumber"`
+      # @param params [Array<Object>] positional JSON-RPC params
+      # @param chain [Chain, nil] chain being queried, used by multi-network transports to pick an endpoint
+      # @return [Object] the raw JSON-RPC `result` (String, Hash, Array, nil...), undecoded
+      # @raise [RpcError] when the node answers with a JSON-RPC error object
+      # @raise [NotImplementedError] when called on {Base} itself
       def request(method, params = [], chain: nil)
         raise NotImplementedError, "#{self.class}#request"
       end
 
-      # Naive batch: one request per call. Transports with real batching override it.
-      # Returns an array of results; failed calls are returned as RpcError instances.
+      # Executes several calls and returns their results in order.
+      #
+      # This naive implementation issues one {#request} per call; transports with real JSON-RPC batching
+      # override it. A call that fails with an {RpcError} does not abort the batch: the error instance takes
+      # the place of its result.
+      #
+      # @param calls [Array<Array(String, Array)>] `[method, params]` pairs; a missing params entry means `[]`
+      # @param chain [Chain, nil] chain being queried, forwarded to {#request}
+      # @return [Array<Object, RpcError>] one raw result (or {RpcError}) per call, in the same order
       def batch(calls, chain: nil)
         calls.map do |(method, params)|
           request(method, params || [], chain: chain)
@@ -20,6 +44,9 @@ module BlockGiven
         end
       end
 
+      # Short lowercase name of the transport, derived from the class name.
+      #
+      # @return [String] e.g. `"http"`, `"alchemy"` or `"stub"`
       def name = self.class.name.split("::").last.downcase
     end
   end

data/lib/block_given/connectors/http.rb

@@ -6,18 +6,55 @@ require "uri"
 
 module BlockGiven
   module Connectors
-    # Generic JSON-RPC over HTTP(S) transport with retries and exponential backoff.
+    # Generic JSON-RPC 2.0 over HTTP(S) transport built on Net::HTTP, with retries and exponential backoff.
     #
+    # Each request is a POST of a JSON body to the endpoint. Transient failures are retried up to `retries`
+    # times, sleeping `retry_delay * 2**(attempt - 1)` seconds between attempts: HTTP statuses listed in
+    # {RETRIABLE_STATUSES}, JSON-RPC error codes listed in {RETRIABLE_RPC_CODES} (never a
+    # {ContractRevertError}) and the network exceptions listed in {RETRIABLE_EXCEPTIONS}. Anything else is
+    # raised immediately as {HttpError} or {RpcError}.
+    #
+    # Endpoints frequently embed an API key in their path, so {#inspect}, log lines and error messages only
+    # ever show the redacted form produced by {#redact} (scheme and host, never the path).
+    #
+    # @example Explicit endpoint (local node, Infura, QuickNode...)
     #   BlockGiven::Connectors::Http.new(url: "http://127.0.0.1:8545")
-    #   BlockGiven::Connectors::Http.new # -> falls back to chain.rpc_urls.first
+    #   BlockGiven::Connectors::Http.new(url: "https://mainnet.infura.io/v3/KEY", timeout: 10, retries: 5)
+    # @example Public RPC of the chain
+    #   BlockGiven::Connectors::Http.new # -> uses chain.rpc_urls.first of the chain passed on each request
     class Http < Base
+      # HTTP status codes that trigger a retry (timeouts, rate limiting, server and gateway errors).
       RETRIABLE_STATUSES = [408, 425, 429, 500, 502, 503, 504].freeze
+      # JSON-RPC error codes that trigger a retry: provider rate limit (-32005), internal error (-32603), 429.
       RETRIABLE_RPC_CODES = [-32_005, -32_603, 429].freeze # rate limited / internal error
+      # Network-level exceptions that trigger a retry; they surface as {HttpError} once retries are exhausted.
       RETRIABLE_EXCEPTIONS = [Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED,
                               Errno::EHOSTUNREACH, EOFError, SocketError, OpenSSL::SSL::SSLError].freeze
 
+      # @!attribute [r] url
+      #   @return [String, nil] fixed endpoint, or nil when the endpoint comes from the chain's `rpc_urls`
+      # @!attribute [r] headers
+      #   @return [Hash{String => String}] request headers sent with every POST (`Content-Type`, `User-Agent`
+      #     and the custom ones given to the constructor)
+      # @!attribute [r] timeout
+      #   @return [Numeric] seconds applied to the open, read and write timeouts of each HTTP request
+      # @!attribute [r] retries
+      #   @return [Integer] maximum number of retries after the first attempt
+      # @!attribute [r] retry_delay
+      #   @return [Numeric] base delay in seconds before the first retry; doubled on each further retry
+
       attr_reader :url, :headers, :timeout, :retries, :retry_delay
 
+      # Builds an HTTP transport.
+      #
+      # @param url [String, nil] JSON-RPC endpoint. When nil, {#endpoint} falls back to the first `rpc_urls`
+      #   entry of the chain given on each request.
+      # @param headers [Hash{String => String}] extra headers merged over the defaults
+      #   (`Content-Type: application/json`, `User-Agent: block_given/<version>`); may override them
+      # @param timeout [Numeric] seconds for the open, read and write timeouts of each HTTP request
+      # @param retries [Integer] number of retries after the first failed attempt (0 disables retrying)
+      # @param retry_delay [Numeric] seconds slept before the first retry; each further retry doubles it
+      # @param logger [Logger, nil] receives retry notices at debug level. Defaults to `BlockGiven.config.logger`.
       def initialize(url: nil, headers: {}, timeout: 30, retries: 3, retry_delay: 0.5, logger: nil)
         super()
         @url = url
@@ -31,6 +68,11 @@ module BlockGiven
         @mutex = Mutex.new
       end
 
+      # Resolves the endpoint used for a request: the fixed `url`, or the chain's first public RPC url.
+      #
+      # @param chain [Chain, nil] chain being queried
+      # @return [String] the endpoint URL (may contain credentials: pass it through {#redact} before logging)
+      # @raise [ConfigurationError] when no `url` was given and the chain has no `rpc_urls`
       def endpoint(chain)
         return url if url
 
@@ -38,12 +80,38 @@ module BlockGiven
           raise(ConfigurationError, "no RPC url: pass url: to the connector or use a chain with rpc_urls")
       end
 
+      # Sends one JSON-RPC 2.0 request (with an auto-incremented id) and returns its `result`.
+      #
+      # Retriable failures are retried with exponential backoff, see the class description.
+      #
+      # @param method [String] JSON-RPC method name
+      # @param params [Array<Object>] positional JSON-RPC params
+      # @param chain [Chain, nil] chain being queried, used to resolve the endpoint when no `url` is fixed
+      # @return [Object] the raw JSON-RPC `result`
+      # @raise [ContractRevertError] when the node reports an EVM revert (never retried)
+      # @raise [RpcError] when the node answers with a JSON-RPC error, or the body is not a JSON object;
+      #   retriable codes are raised only once retries are exhausted
+      # @raise [HttpError] on a non-2xx status, an invalid JSON body or a network error (after retries)
+      # @raise [ConfigurationError] when no endpoint can be resolved
       def request(method, params = [], chain: nil)
         payload = { jsonrpc: "2.0", id: next_id, method: method, params: params }
         body = with_retries(method) { post(endpoint(chain), payload) }
         handle_single(body, method)
       end
 
+      # Sends several calls in one JSON-RPC batch request (a single HTTP POST with an array body).
+      #
+      # Responses are matched to calls by id, so the node may answer in any order. A call whose response
+      # carries an `error` (or is missing from the response) yields an {RpcError} instance in its slot instead
+      # of raising. Only transport-level failures of the whole batch are retried.
+      #
+      # @param calls [Array<Array(String, Array)>] `[method, params]` pairs; a missing params entry means `[]`
+      # @param chain [Chain, nil] chain being queried, used to resolve the endpoint when no `url` is fixed
+      # @return [Array<Object, RpcError>] one raw result (or {RpcError}) per call, in call order; `[]` for
+      #   an empty `calls` (no request is sent)
+      # @raise [RpcError] when the node does not answer with a JSON array
+      # @raise [HttpError] on a non-2xx status, an invalid JSON body or a network error (after retries)
+      # @raise [ConfigurationError] when no endpoint can be resolved
       def batch(calls, chain: nil)
         return [] if calls.empty?
 
@@ -62,10 +130,21 @@ module BlockGiven
         end
       end
 
+      # Short description showing the redacted endpoint (or `chain default`), never the full URL.
+      #
+      # @return [String]
       def inspect = "#<#{self.class.name} url=#{url ? redact(url).inspect : 'chain default'}>"
 
-      # Endpoint as it may appear in logs and error messages. RPC URLs usually carry
-      # the API key in their path (Infura, QuickNode, ...), so only scheme and host are kept.
+      # Endpoint as it may appear in logs and error messages.
+      #
+      # RPC URLs usually carry the API key in their path (Infura, QuickNode, ...), so only the scheme and the
+      # host (plus a non-default port) are kept; a non-empty path is replaced by `/…`.
+      #
+      # @example
+      #   connector.redact("https://mainnet.infura.io/v3/SECRET") # => "https://mainnet.infura.io/…"
+      #   connector.redact("http://127.0.0.1:8545")               # => "http://127.0.0.1:8545"
+      # @param endpoint [String, URI::Generic] URL to redact
+      # @return [String] the redacted URL, or `"<invalid url>"` when it cannot be parsed
       def redact(endpoint)
         uri = URI.parse(endpoint.to_s)
         host = uri.port && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
@@ -95,10 +174,17 @@ module BlockGiven
         body["result"]
       end
 
-      # Internal signal used to retry on retriable JSON-RPC errors.
+      # Internal signal raised by {Http#handle_single} to retry on a retriable JSON-RPC error; the original
+      # {RpcError} is re-raised once retries are exhausted.
+      #
+      # @api private
       class Retry < StandardError
+        # The retriable JSON-RPC error that triggered the retry.
+        #
+        # @return [RpcError]
         attr_reader :cause_error
 
+        # @param cause_error [RpcError] the retriable JSON-RPC error; its message becomes this error's message
         def initialize(cause_error)
           @cause_error = cause_error
           super(cause_error.message)

data/lib/block_given/connectors/stub.rb

@@ -2,29 +2,70 @@
 
 module BlockGiven
   module Connectors
-    # In-memory connector for tests. Responses can be static values, sequences
-    # (consumed in order, last value repeats) or procs receiving the params.
+    # In-memory connector for tests: no network, canned responses, and a record of every call.
     #
+    # Responses are registered per JSON-RPC method name and can be:
+    # - a static value, returned on every call;
+    # - a {Sequence} built with {Stub.sequence}, consumed in order, the last value repeating forever;
+    # - a Proc receiving the request params, for param-dependent answers;
+    # - an Exception instance, raised instead of returned (e.g. an {RpcError} to simulate a node error).
+    # A handler block given to {Stub#initialize} answers every method without a registered response. Methods with
+    # neither raise an {RpcError} with code -32601 ("method not found").
+    #
+    # @example Static values, a sequence and a proc
     #   stub = BlockGiven::Connectors::Stub.new(
+    #     "eth_chainId" => "0x2105",
     #     "eth_blockNumber" => BlockGiven::Connectors::Stub.sequence("0x10", "0x11"),
-    #     "eth_call" => ->(params) { "0x" + "0" * 63 + "1" }
+    #     "eth_call" => ->(params) { params.first[:to] == usdc ? "0x" + "0" * 63 + "1" : "0x" }
     #   )
-    #   stub.calls # => [["eth_blockNumber", []], ...]
+    #   client = BlockGiven::Client.new(chain: :base, connector: stub)
+    #   client.block_number       # => 16
+    #   client.block_number       # => 17 (and 17 again afterwards)
+    #   stub.calls                # => [["eth_blockNumber", []], ["eth_blockNumber", []]]
+    #   stub.calls_for("eth_call") # => params of each eth_call
+    # @example Fallback handler and incremental stubbing
+    #   stub = BlockGiven::Connectors::Stub.new { |method, params, chain| raise "unexpected #{method}" }
+    #   stub.stub("eth_gasPrice", "0x3b9aca00").stub("eth_estimateGas") { |params| "0x5208" }
     class Stub < Base
+      # Ordered list of canned responses: each call consumes the next value, the last one repeats forever.
+      # Build one with {Stub.sequence}.
       class Sequence
+        # @param values [Array<Object>] responses in the order they should be served (copied, not mutated)
         def initialize(values)
           @values = values.dup
         end
 
+        # Consumes and returns the next value; once a single value is left it is returned on every call.
+        #
+        # @return [Object, nil] the next response (nil for an empty sequence)
         def next
           @values.size > 1 ? @values.shift : @values.first
         end
       end
 
+      # Builds a {Sequence} of responses for a stubbed method.
+      #
+      # @example
+      #   stub.stub("eth_blockNumber", BlockGiven::Connectors::Stub.sequence("0x10", "0x11", "0x12"))
+      # @param values [Array<Object>] responses served in order; the last one repeats once reached
+      # @return [Sequence]
       def self.sequence(*values) = Sequence.new(values)
 
+      # @!attribute [r] calls
+      #   @return [Array<Array(String, Array)>] every request received so far as `[method, params]` pairs, in
+      #     order, including those that raised; cleared by {#reset!}
+
       attr_reader :calls
 
+      # Builds a stub connector with an initial set of canned responses and an optional fallback handler.
+      #
+      # @param responses [Hash{String, Symbol => Object}] method name to response (static value, {Sequence},
+      #   Proc receiving the params, or Exception to raise); each entry goes through {#stub}
+      # @yield [method, params, chain] for every request whose method has no registered response
+      # @yieldparam method [String] JSON-RPC method name
+      # @yieldparam params [Array<Object>] request params
+      # @yieldparam chain [Chain, nil] chain passed by the client
+      # @yieldreturn [Object] the value to use as the JSON-RPC `result` (raised when it is an Exception)
       def initialize(responses = {}, &handler)
         super()
         @responses = {}
@@ -33,11 +74,28 @@ module BlockGiven
         responses.each { |method, value| stub(method, value) }
       end
 
+      # Registers (or replaces) the response of one JSON-RPC method.
+      #
+      # @param method [String, Symbol] JSON-RPC method name
+      # @param value [Object, Sequence, Proc, Exception, nil] static value, {Sequence}, Proc receiving the params,
+      #   or Exception instance to raise; ignored when a block is given
+      # @yield [params] when a block is given it computes the response on every call
+      # @yieldparam params [Array<Object>] request params
+      # @yieldreturn [Object] the value to use as the JSON-RPC `result` (raised when it is an Exception)
+      # @return [self] for chaining
       def stub(method, value = nil, &block)
         @responses[method.to_s] = block || value
         self
       end
 
+      # Records the call and returns the canned response for `method`.
+      #
+      # @param method [String, Symbol] JSON-RPC method name
+      # @param params [Array<Object>] request params, recorded and passed to Proc responses / the handler
+      # @param chain [Chain, nil] chain passed by the client, forwarded to the handler block only
+      # @return [Object] the resolved response (a {Sequence} is advanced, a Proc is called with `params`)
+      # @raise [Exception] the resolved response itself when it is an Exception instance
+      # @raise [RpcError] with code -32601 when the method has no response and no handler was given
       def request(method, params = [], chain: nil)
         @calls << [method.to_s, params]
         value = resolve(method.to_s, params, chain)
@@ -46,7 +104,15 @@ module BlockGiven
         value
       end
 
+      # Params of every recorded call to one method, in order.
+      #
+      # @param method [String, Symbol] JSON-RPC method name
+      # @return [Array<Array<Object>>] one params Array per call (empty when the method was never called)
       def calls_for(method) = calls.select { |(m, _)| m == method.to_s }.map(&:last)
+
+      # Forgets every recorded call; registered responses (and sequence positions) are kept.
+      #
+      # @return [Array] the emptied {#calls} Array
       def reset! = @calls.clear
 
       private