nwc-ruby 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33006d633764a07adc713f4e5e6fe49a5108927286258abf0d976076a3f125d1
-  data.tar.gz: 4727a1b8968c741a2ec2feb2c4f576b4afe8d4df2066f09ddf26f6eb53ed42a1
+  metadata.gz: 9b1fb35da37743ef772eac5368822e3656d24a8f1b081fa02174f52084ea0d03
+  data.tar.gz: '086309565529631e6525c95a22736b86423969216bc12f7ea2e63c65c9cc713e'
 SHA512:
-  metadata.gz: 6fc9796e80a92b9e1d255ee2fdafb85d5171c7a74a6d25b522ddebf2114620081775a7a21d409ff6209a2d522e02451d6f3057627dd07e2f7091bbba779639a4
-  data.tar.gz: '087888d35e9b84ad81a8ab1f97ee1914a75b2d32a3632c62972bda323225d83eb082fb3e02df469138a980795e3e62692ba9877a0bb398ed228d6a9337f622bd'
+  metadata.gz: 54b83902f9b0f3a0cd3df5f453d07d90e31a72b18cb81c888b9635ea44c7d34f804b15a0c6d77ab5fca3bad85be99adb73cf91cc22fb76fed94da35300d63f37
+  data.tar.gz: 1871b89d77fbac48fb8731ed8ae56c99a3555289313af614b2b1bf13704fca12a64c4233b92ac0fafcd469db1b0fb501b841eba202b21b528698f919eee06183

data/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-10-05
+
+### Changed
+
+- **Failures now say whether the request reached the wallet.** Anything that
+  fails before the request EVENT is written to the relay — DNS, TCP connect,
+  TLS, the websocket upgrade, the info fetch — raises the new
+  `NwcRuby::NotSentError` (a `TransportError` subclass, so existing rescues
+  still match), with the original exception as `#cause` and only the relay
+  host in the message. Failures after the write stay ambiguous:
+  `TransportError` or `TimeoutError`. Previously a DNS failure surfaced as a
+  raw `Socket::ResolutionError`, so callers could not tell "never sent, safe
+  to retry" from "maybe paid".
+- Public `Client` methods no longer leak raw `SocketError` / `Errno::*` /
+  `OpenSSL::SSL::SSLError` / `Async::TimeoutError` / `Protocol::WebSocket`
+  exceptions; everything is an `NwcRuby::Error`.
+- A relay closing the connection after the request was sent now raises
+  `TransportError` instead of a misleading `TimeoutError`.
+- A relay answering the request with `["OK", id, false, reason]` now raises
+  `TransportError` immediately instead of waiting out `request_timeout`. It is
+  still treated as maybe-sent, since the relay is untrusted.
+- "No info event" is now `InfoUnavailableError` (a `NotSentError`) instead of a
+  plain `TransportError`.
+- `request_timeout` now bounds the whole call, including connecting and the
+  info fetch. Before, a relay that went silent could block a request
+  indefinitely because the deadline was only checked when a message arrived.
+- Errors are classified inside the Async task, so Async no longer logs
+  "Task may have ended with unhandled exception" for request failures.
+
+### Added
+
+- `connect_retries:` (default 2): pre-send failures are retried with 0.25 s /
+  1 s backoff inside `request_timeout`. Nothing is retried after the request is
+  written.
+- Requests and info fetches fall through to the next `relay` in the connection
+  string on a pre-send failure (previously only the first relay was used).
+- `NwcRuby::Error#sent?` — `false` for `NotSentError` and
+  `UnsupportedMethodError`, `true` for `TransportError`, `TimeoutError` and
+  `WalletServiceError`, `nil` where it doesn't apply.
+
 ## [0.2.4] — 2026-07-17
 
 ### Security

data/README.md

@@ -522,6 +522,12 @@ Constructor:
 | `Client.from_uri(uri)`          | `Client` — parses the `nostr+walletconnect://` URI  |
 | `Client.new(connection_string)` | `Client` — if you already have a `ConnectionString` |
 
+Both accept `request_timeout:` (seconds, default 30, covering the info fetch,
+connect and response wait) and `connect_retries:` (default 2). Failures before
+the request is written to the relay are retried across every `relay` in the
+connection string, with 0.25 s / 1 s backoff, inside `request_timeout`.
+Nothing is ever retried after the request is written.
+
 Introspection:
 
 | Method            | Returns                                  |
@@ -565,19 +571,42 @@ Listener:
 
 ### Errors
 
-All gem errors inherit from `NwcRuby::Error`:
+All gem errors inherit from `NwcRuby::Error`. Public `Client` methods never
+let a raw `SocketError` / `Errno::*` / `OpenSSL` / `Async` exception escape;
+the original is kept as `#cause`.
 
 - `InvalidConnectionStringError` — the URI couldn't be parsed.
 - `EncryptionError` — bad MAC / bad padding / unknown version byte / bad key.
 - `InvalidSignatureError` — an event's signature did not verify.
-- `TransportError` — the WebSocket couldn't connect or died unrecoverably.
-- `TimeoutError` — no response within the timeout window.
+- `TransportError` — the connection failed **after** the request was written
+  to the relay. The wallet may have acted on it: reconcile with
+  `lookup_invoice` / `list_transactions` rather than retrying a payment.
+  - `NotSentError` — the request never left this process (DNS, connect, TLS,
+    websocket upgrade, info fetch). Always safe to retry.
+    - `InfoUnavailableError` — the relay holds no kind 13194 info event for
+      this wallet; usually a wrong relay or pubkey.
+- `TimeoutError` — the request was sent but no response arrived in time. The
+  wallet may have acted on it.
 - `UnsupportedMethodError` — wallet service doesn't advertise this method.
+  A configuration problem; retrying won't help.
 - `WalletServiceError` — the wallet returned an error envelope. Check `#code`
   for `RATE_LIMITED`, `NOT_IMPLEMENTED`, `INSUFFICIENT_BALANCE`,
   `QUOTA_EXCEEDED`, `RESTRICTED`, `UNAUTHORIZED`, `INTERNAL`,
   `UNSUPPORTED_ENCRYPTION`, `PAYMENT_FAILED`, `NOT_FOUND`, or `OTHER`.
 
+Every error also answers `#sent?`: `false` means the request provably never
+reached the wallet; `true` or `nil` mean it may have.
+
+```ruby
+begin
+  client.pay_invoice(invoice: bolt11)
+rescue NwcRuby::NotSentError
+  # Nothing reached the wallet. Safe to retry later.
+rescue NwcRuby::TransportError, NwcRuby::TimeoutError
+  # Ambiguous: the payment may have gone out. Reconcile before retrying.
+end
+```
+
 ---
 
 ## Security notes

data/lib/nwc_ruby/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'async'
+require 'async/clock'
 require 'async/http/endpoint'
 require 'async/websocket/client'
 
@@ -19,7 +20,10 @@ module NwcRuby
   #     puts "Got #{notification.amount_msats} msats"
   #   end
   class Client
-    DEFAULT_TIMEOUT = 30
+    DEFAULT_TIMEOUT         = 30
+    DEFAULT_CONNECT_RETRIES = 2
+    # Pause before each retry round; the last value repeats.
+    CONNECT_BACKOFF = [0.25, 1.0].freeze
 
     attr_reader :connection_string, :logger
 
@@ -27,10 +31,16 @@ module NwcRuby
       new(ConnectionString.parse(uri_string), **)
     end
 
-    def initialize(connection_string, logger: nil, request_timeout: DEFAULT_TIMEOUT)
+    # @param request_timeout [Numeric] overall budget per public call, covering
+    #   the info fetch, connecting, and waiting for the wallet's response.
+    # @param connect_retries [Integer] extra rounds through the relay list when
+    #   a request fails before it is sent. Never applies after sending.
+    def initialize(connection_string, logger: nil, request_timeout: DEFAULT_TIMEOUT,
+                   connect_retries: DEFAULT_CONNECT_RETRIES)
       @connection_string = connection_string
       @logger            = logger || default_logger
       @request_timeout   = request_timeout
+      @connect_retries   = connect_retries
       @info              = nil
     end
 
@@ -38,10 +48,11 @@ module NwcRuby
 
     # Fetch and cache the kind 13194 info event. This tells us which methods
     # the wallet service supports and which encryption schemes it accepts.
+    # Raises NotSentError (never anything lower-level) if it can't be fetched.
     def info(refresh: false)
       return @info if @info && !refresh
 
-      @info = fetch_info
+      @info = fetch_info(new_deadline)
     end
 
     def capabilities
@@ -248,124 +259,203 @@ module NwcRuby
       }
     end
 
-    # rubocop:disable Metrics/MethodLength
+    def response_filter(request_id)
+      {
+        'authors' => [@connection_string.wallet_pubkey],
+        'kinds' => [NIP47::Methods::KIND_RESPONSE],
+        '#e' => [request_id],
+        '#p' => [@connection_string.client_pubkey]
+      }
+    end
+
+    # Every request has two phases. Phase 1 (info fetch, DNS, connect, TLS,
+    # upgrade, REQ write) cannot have reached the wallet, so its failures raise
+    # NotSentError and are retried. Phase 2 starts at the EVENT write: the
+    # wallet may have acted, so failures there are ambiguous and never retried.
     def call(method, params)
-      ensure_supports!(method)
-      encryption = info.preferred_encryption
-
-      deadline = Time.now + @request_timeout
-      result   = nil
-
-      Async do
-        endpoint = Async::HTTP::Endpoint.parse(@connection_string.relays.first, alpn_protocols: ['http/1.1'])
-        Async::WebSocket::Client.connect(endpoint) do |conn|
-          request_event = NIP47::Request.build(
-            method: method,
-            params: params,
-            client_privkey: @connection_string.secret,
-            wallet_pubkey: @connection_string.wallet_pubkey,
-            encryption: encryption
-          )
-
-          sub_id = "rsp-#{SecureRandom.hex(4)}"
-          conn.write(Protocol::WebSocket::TextMessage.generate(['REQ', sub_id, {
-                                                                 'authors' => [@connection_string.wallet_pubkey],
-                                                                 'kinds' => [NIP47::Methods::KIND_RESPONSE],
-                                                                 '#e' => [request_event.id],
-                                                                 '#p' => [@connection_string.client_pubkey]
-                                                               }]))
-          conn.write(Protocol::WebSocket::TextMessage.generate(['EVENT', request_event.to_h]))
-          conn.flush
-
-          while (msg = conn.read)
-            break if Time.now > deadline
-
-            parsed = begin
-              JSON.parse(msg.buffer)
-            rescue JSON::ParserError
-              next
-            end
-
-            next unless parsed[0] == 'EVENT' && parsed[1] == sub_id
-
-            event = Event.from_hash(parsed[2])
-            next unless authentic?(event)
-            next unless event.kind == NIP47::Methods::KIND_RESPONSE
-            next unless response_to?(event, request_event.id)
-
-            result = NIP47::Response.parse(event, @connection_string.secret, @connection_string.wallet_pubkey)
-            break
-          end
-        ensure
-          begin
-            conn&.close
-          rescue StandardError
-            nil
-          end
-        end
-      end.wait
-
-      raise TimeoutError, "no response to #{method} within #{@request_timeout}s" if result.nil?
-      raise WalletServiceError.new(result.error_code || 'UNKNOWN', result.error_message || '') unless result.success?
-
-      result.result
-    end
-    # rubocop:enable Metrics/MethodLength
-
-    def fetch_info
-      endpoint  = Async::HTTP::Endpoint.parse(@connection_string.relays.first, alpn_protocols: ['http/1.1'])
-      deadline  = Time.now + @request_timeout
-      result    = nil
-
-      Async do
-        Async::WebSocket::Client.connect(endpoint) do |conn|
-          sub_id = "info-#{SecureRandom.hex(4)}"
-          conn.write(Protocol::WebSocket::TextMessage.generate(['REQ', sub_id, info_filter]))
-          conn.flush
-
-          while (msg = conn.read)
-            break if Time.now > deadline
-
-            parsed = begin
-              JSON.parse(msg.buffer)
-            rescue JSON::ParserError
-              next
-            end
-
-            if parsed[0] == 'EVENT' && parsed[1] == sub_id
-              event = Event.from_hash(parsed[2])
-              # A rejected event must not end the read: a genuine info event
-              # may still follow, and the deadline above bounds the wait.
-              next unless authentic?(event) && event.kind == NIP47::Methods::KIND_INFO
-
-              result = NIP47::Info.parse(event)
-              break
-            elsif parsed[0] == 'EOSE' && parsed[1] == sub_id
-              break
-            end
-          end
-        ensure
-          begin
-            conn&.close
-          rescue StandardError
-            nil
-          end
+      deadline = new_deadline
+      ensure_supports!(method, deadline)
+
+      # Built once so every relay and retry carries the same event id.
+      request_event = NIP47::Request.build(
+        method: method,
+        params: params,
+        client_privkey: @connection_string.secret,
+        wallet_pubkey: @connection_string.wallet_pubkey,
+        encryption: @info.preferred_encryption
+      )
+
+      response = with_relays(deadline) { |url| send_request(url, deadline, method, request_event) }
+      unless response.success?
+        raise WalletServiceError.new(response.error_code || 'UNKNOWN', response.error_message || '')
+      end
+
+      response.result
+    end
+
+    def send_request(url, deadline, method, request_event)
+      sent = false
+      response, failure = websocket_session(url, deadline) do |conn|
+        sub_id = "rsp-#{SecureRandom.hex(4)}"
+        write_frame(conn, ['REQ', sub_id, response_filter(request_event.id)])
+        # Set before the write: a write that fails part-way may still deliver.
+        sent = true
+        write_frame(conn, ['EVENT', request_event.to_h])
+        read_response(conn, sub_id, request_event.id)
+      end
+      return response if response
+
+      raise_not_sent(url, failure) unless sent
+      raise failure if failure.is_a?(Error)
+      if failure.is_a?(Async::TimeoutError)
+        raise TimeoutError, "no response to #{method} within #{@request_timeout}s", cause: failure
+      end
+
+      raise TransportError,
+            "connection to relay #{relay_host(url)} failed after #{method} was sent " \
+            "(#{failure.class}: #{failure.message})",
+            cause: failure
+    end
+
+    def read_response(conn, sub_id, request_id)
+      while (msg = conn.read)
+        parsed = parse_frame(msg)
+        # Still ambiguous: the relay is untrusted and may have forwarded it anyway.
+        if parsed && parsed[0] == 'OK' && parsed[1] == request_id && parsed[2] == false
+          raise TransportError, "relay rejected the request: #{parsed[3].to_s[0, 200]}"
         end
-      end.wait
 
-      if result.nil?
-        raise TransportError,
-              "wallet service published no info event (kind 13194) on #{@connection_string.relays.first}"
+        event = relay_event(parsed, sub_id)
+        next unless event && event.kind == NIP47::Methods::KIND_RESPONSE && response_to?(event, request_id)
+
+        return NIP47::Response.parse(event, @connection_string.secret, @connection_string.wallet_pubkey)
+      end
+      raise TransportError, 'relay closed the connection before the wallet responded'
+    end
+
+    # Entirely phase 1: nothing has been sent to the wallet yet.
+    def fetch_info(deadline)
+      with_relays(deadline) { |url| fetch_info_from(url, deadline) }
+    end
+
+    def fetch_info_from(url, deadline)
+      info, failure = websocket_session(url, deadline) do |conn|
+        sub_id = "info-#{SecureRandom.hex(4)}"
+        write_frame(conn, ['REQ', sub_id, info_filter])
+        read_info(conn, sub_id)
       end
+      return info if info
 
-      result
+      raise_not_sent(url, failure) if failure
+      raise InfoUnavailableError,
+            "wallet service published no info event (kind 13194) on relay #{relay_host(url)}"
     end
 
-    def ensure_supports!(method)
-      return if info.supports?(method)
+    def read_info(conn, sub_id)
+      while (msg = conn.read)
+        parsed = parse_frame(msg)
+        return nil if parsed && parsed[0] == 'EOSE' && parsed[1] == sub_id
+
+        # A rejected event must not end the read: a genuine info event may
+        # still follow, and the deadline bounds the wait.
+        event = relay_event(parsed, sub_id)
+        return NIP47::Info.parse(event) if event&.kind == NIP47::Methods::KIND_INFO
+      end
+      nil
+    end
+
+    def ensure_supports!(method, deadline)
+      @info ||= fetch_info(deadline)
+      return if @info.supports?(method)
 
       raise UnsupportedMethodError,
-            "wallet service does not advertise `#{method}`. Supported: #{info.methods.join(', ')}"
+            "wallet service does not advertise `#{method}`. Supported: #{@info.methods.join(', ')}"
+    end
+
+    # Tries each relay in turn, then up to @connect_retries more rounds with
+    # backoff, all inside `deadline`. Only NotSentError is retried.
+    def with_relays(deadline)
+      last_failure = nil
+      (@connect_retries + 1).times do |round|
+        if round.positive?
+          pause = CONNECT_BACKOFF[round - 1] || CONNECT_BACKOFF.last
+          break if Async::Clock.now + pause >= deadline
+
+          sleep pause
+        end
+
+        @connection_string.relays.each do |url|
+          break if Async::Clock.now >= deadline
+
+          return yield(url)
+        rescue NotSentError => e
+          last_failure = e
+          @logger.warn("[nwc] #{e.message}")
+        end
+      end
+      raise last_failure if last_failure
+
+      raise NotSentError, "not sent: #{@request_timeout}s deadline passed before a relay could be tried"
+    end
+
+    # One websocket session bounded by `deadline`. Exceptions are rescued
+    # inside the task and returned so Async never logs them as unhandled.
+    # @return [Array(Object, Exception)] the block's value and any failure
+    def websocket_session(url, deadline)
+      value   = nil
+      failure = nil
+      Sync do |task|
+        task.with_timeout(remaining(deadline)) do
+          endpoint = Async::HTTP::Endpoint.parse(url, alpn_protocols: ['http/1.1'])
+          Async::WebSocket::Client.connect(endpoint) { |conn| value = yield(conn) }
+        end
+      rescue StandardError => e
+        failure = e
+      end
+      [value, failure]
+    end
+
+    def raise_not_sent(url, failure)
+      raise failure if failure.is_a?(NotSentError)
+
+      reason = failure.is_a?(Async::TimeoutError) ? 'timed out' : "#{failure.class}: #{failure.message}"
+      raise NotSentError, "not sent: relay #{relay_host(url)} failed before the request was written (#{reason})",
+            cause: failure
+    end
+
+    # An authentic wallet event delivered on `sub_id`, or nil.
+    def relay_event(parsed, sub_id)
+      return unless parsed && parsed[0] == 'EVENT' && parsed[1] == sub_id && parsed[2].is_a?(Hash)
+
+      event = Event.from_hash(parsed[2])
+      event if authentic?(event)
+    end
+
+    def parse_frame(msg)
+      parsed = JSON.parse(msg.buffer)
+      parsed if parsed.is_a?(Array)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def write_frame(conn, message)
+      conn.write(Protocol::WebSocket::TextMessage.generate(message))
+      conn.flush
+    end
+
+    # Host only: relay URLs can carry auth tokens in the path or query.
+    def relay_host(url)
+      URI.parse(url).host || 'unknown'
+    rescue URI::InvalidURIError
+      'unparseable relay URL'
+    end
+
+    def new_deadline
+      Async::Clock.now + @request_timeout
+    end
+
+    def remaining(deadline)
+      [deadline - Async::Clock.now, 0].max
     end
 
     def default_logger

data/lib/nwc_ruby/errors.rb

@@ -2,7 +2,11 @@
 
 module NwcRuby
   # Base class for all gem errors. Rescue this to catch anything the gem raises.
-  class Error < StandardError; end
+  class Error < StandardError
+    # Whether the request reached the relay. Only `false` is a safe-to-retry
+    # signal; `true` and `nil` mean the wallet may have acted on it.
+    def sent? = nil # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+  end
 
   # The connection string is missing or malformed.
   class InvalidConnectionStringError < Error; end
@@ -13,9 +17,24 @@ module NwcRuby
   # Signature verification failed on an inbound event.
   class InvalidSignatureError < Error; end
 
-  # The relay could not be reached, or the connection died and did not recover
-  # within the configured timeout.
-  class TransportError < Error; end
+  # The connection to the relay failed after the request was written to it.
+  # The wallet may have acted on the request, so do not blindly retry
+  # payments; reconcile with `lookup_invoice` / `list_transactions` instead.
+  # (`NotSentError` below is the safe-to-retry subclass.)
+  class TransportError < Error
+    def sent? = true
+  end
+
+  # The request never left this process: DNS, TCP connect, TLS, the websocket
+  # upgrade, or the info fetch failed first. Always safe to retry. `#cause`
+  # holds the original low-level exception.
+  class NotSentError < TransportError
+    def sent? = false
+  end
+
+  # The relay answered but holds no kind 13194 info event for this wallet.
+  # Usually a wrong relay or wallet pubkey rather than a transient fault.
+  class InfoUnavailableError < NotSentError; end
 
   # The wallet service returned an error envelope. `#code` is the NIP-47 error
   # code (one of RATE_LIMITED, NOT_IMPLEMENTED, INSUFFICIENT_BALANCE,
@@ -28,12 +47,20 @@ module NwcRuby
       @code = code
       super("#{code}: #{message}")
     end
+
+    def sent? = true
   end
 
-  # A request was sent but no response arrived within the timeout window.
-  class TimeoutError < Error; end
+  # A request was sent but no response arrived within the timeout window. The
+  # wallet may have acted on it.
+  class TimeoutError < Error
+    def sent? = true
+  end
 
   # The wallet service does not support the method we tried to call. Check
-  # `Client#capabilities` first, or use a read+write NWC string.
-  class UnsupportedMethodError < Error; end
+  # `Client#capabilities` first, or use a read+write NWC string. A
+  # configuration problem: retrying will not help.
+  class UnsupportedMethodError < Error
+    def sent? = false
+  end
 end

data/lib/nwc_ruby/test_runner.rb

@@ -303,7 +303,7 @@ module NwcRuby
       rescue TimeoutError => e
         fail!("#{label}: #{e.message}")
         fail!('  → The wallet service accepted the request but never responded. The service may be down or overloaded.')
-      rescue UnsupportedMethodError => e
+      rescue UnsupportedMethodError, TransportError => e
         fail!("#{label}: #{e.message}")
       rescue EncryptionError => e
         fail!("#{label}: decryption failed — #{e.message}")

data/lib/nwc_ruby/transport/relay_connection.rb

@@ -120,7 +120,7 @@ module NwcRuby
       # Send raw client->relay message (e.g. REQ, EVENT, CLOSE). Safe to call
       # from within on_open / on_event callbacks.
       def send_message(message)
-        raise TransportError, 'not connected' unless @conn
+        raise NotSentError, 'not connected' unless @conn
 
         @conn.write(Protocol::WebSocket::TextMessage.generate(message))
         @conn.flush

data/lib/nwc_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NwcRuby
-  VERSION = '0.2.4'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nwc-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - MegalithicBTC