nwc-ruby 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97f270975d59347524e31943926149e2d361833a5ab9dd7c580cf00281b5fec9
-  data.tar.gz: 99b7a6b3a40c8c0f7ca30408f34afb653fab4c5afb8c69327e79be3a00afa663
+  metadata.gz: b847b05f148d03753548528e0f4483129cf59887e40329f28e7bbe31f0eda1cd
+  data.tar.gz: 9c99704df81a6e7cfa9c1bfede014b49270b15bf11a3bba8663b5d6f1f3500fa
 SHA512:
-  metadata.gz: 96bc19c5c7ee1ac4794c76be6aa9e64b9aeddf7d89d5a4df88134104f07e65a40c1466efa54ffea9df546d55a92bb06c27e2ee1e8397d3c9459272bca6065526
-  data.tar.gz: 20f46cf66670993db5c8fa351e2bc95b611c7ad994dd7d64495927ffac5347c8b9a1a8767cb19dd16a2deb2dea869086ae8ae606a13211f55f3546156526afd8
+  metadata.gz: 11e62747c2dfa88459d900a2e1f89e7a42df5420b88221508bf62df39b65ebe7f9937db357557b2ab3ee8b95be0b50b5062fa3667cf21002dbf607366f49675d
+  data.tar.gz: c0ff4c40f5d8fa68d3b12e6b7c745ff1ff5b19da5719c0998c8cc5db6098ee77917c2c914b0ca96dc9e9301ac4240595f7e472019e6001394c996e75ffdcff6a

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] — 2026-04-21
+
+### Fixed
+
+- Ctrl+C / SIGINT / SIGTERM now reliably exits the notification listener. The
+  previous trap handler called `@conn.close` directly, which deadlocks because
+  closing an SSL socket from inside a Ruby signal handler is unsafe
+  (`docker stop` was the only way out).
+- Replaced the trap-based close with a self-pipe: the trap only flips `@stop`
+  and writes one byte to a pipe; an `Async` task reads from the pipe inside the
+  reactor and calls `top.stop` from the correct fiber context. This avoids two
+  further async-specific pitfalls discovered along the way — `Async::Task#stop`
+  raises `ThreadError: can't be called from trap context` (uses a Mutex), and
+  offloading to `Thread.new { task.stop }` fails with `NoMethodError` on
+  `Fiber.scheduler` because the reactor lives on a different thread.
+- Added `rescue Interrupt, Async::Stop` at the top of the reconnect-loop rescue
+  chain in `RelayConnection#run!` so the stop signal is not swallowed by the
+  generic reconnect-on-error path.
+
+## [0.2.1] — 2026-04-20
+
+### Fixed
+
+- Fixed all RuboCop offenses (CI now passes clean).
+- Extracted `start_heartbeat` / `start_poll` from `run_one_connection` to reduce
+  method length and perceived complexity.
+- Corrected README and CHANGELOG: transport uses 15 s ping keepalive (not 30 s
+  ping + 45 s pong deadline — the pong deadline was removed in 0.1.1 due to
+  async-websocket 0.30 API changes).
+- Fixed string quoting, hash alignment, guard clause, and line length offenses
+  across Rakefile, `bin/nwc_test`, `client.rb`, `test_runner.rb`, and
+  `relay_connection.rb`.
+- Excluded `lib/nwc-ruby.rb` from `Naming/FileName` (compatibility shim).
+
 ## [0.2.0] — 2026-04-20
 
 ### Changed
@@ -52,9 +86,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `multi_pay_keysend`, `make_invoice`, `lookup_invoice`, `list_transactions`,
   `get_balance`, `get_info`, `sign_message`.
 - Notification listener (kinds 23196 and 23197) with dedupe by `payment_hash`.
-- Reliable long-running `Transport::RelayConnection`: RFC 6455 ping (30 s),
-  pong deadline (45 s), forced recycle (5 min), capped exponential backoff,
-  SIGTERM/SIGINT handling.
+- Reliable long-running `Transport::RelayConnection`: RFC 6455 ping (15 s),
+  forced recycle (5 min), capped exponential backoff, SIGTERM/SIGINT handling.
 - `NwcRuby.test` and `NwcRuby.test_notifications` diagnostic methods, backed
   by `NwcRuby::TestRunner`. Announces read-only vs read+write, exercises every
   advertised method, pays a Lightning address if the code is read+write.

data/README.md

@@ -34,8 +34,8 @@ heartbeats, zombie-TCP detection, reconnects, and backoff. You call methods.
 - **Both encryption schemes** — NIP-44 v2 when the wallet advertises it
   (validated against [paulmillr's test vectors][vectors]), NIP-04 fallback for
   wallets that haven't migrated.
-- **Bulletproof long-running transport** — 30 s ping, 45 s pong deadline, 5-min
-  forced recycle, capped exponential backoff, clean SIGTERM handling. Built on
+- **Bulletproof long-running transport** — 15 s ping keepalive, 5-min forced
+  recycle, capped exponential backoff, clean SIGTERM handling. Built on
   [async-websocket][aw] (no dead EventMachine dependency).
 - **Two diagnostic methods** — `NwcRuby.test` (info, read tests, write test
   if applicable) and `NwcRuby.test_notifications` (listen forever in a separate
@@ -211,10 +211,10 @@ end
 ```
 
 Under the hood, this subscribes to both kind 23196 (NIP-04) and kind 23197
-(NIP-44 v2), dedupes by `payment_hash`, sends a WebSocket ping every 30 seconds,
-reconnects with exponential backoff if the pong deadline is missed, and
-force-recycles the connection every 5 minutes as a belt-and-suspenders check
-against middleboxes that silently drop stale TCP streams.
+(NIP-44 v2), dedupes by `payment_hash`, sends a WebSocket ping every 15 seconds
+to keep middleboxes from idle-closing the socket, reconnects with capped
+exponential backoff on failure, and force-recycles the connection every 5 minutes
+as a belt-and-suspenders check against silently dead TCP streams.
 
 #### Resuming after a restart
 

data/lib/nwc_ruby/client.rb

@@ -143,7 +143,7 @@ module NwcRuby
     # @param kinds [Array<Integer>] notification kinds to listen for. Defaults
     #   to both NIP-04 (23196) and NIP-44 v2 (23197). The listener dedupes by
     #   `payment_hash`, so receiving both is safe.
-    def subscribe_to_notifications(since: Time.now.to_i,
+    def subscribe_to_notifications(since: Time.now.to_i, # rubocop:disable Metrics/MethodLength
                                    kinds: [NIP47::Methods::KIND_NOTIFICATION_NIP04,
                                            NIP47::Methods::KIND_NOTIFICATION_NIP44],
                                    sub_id: "nwc-#{SecureRandom.hex(4)}",
@@ -168,7 +168,10 @@ module NwcRuby
       @notification_connection = conn
 
       conn.on_open do |c|
-        @logger.info("[nwc] subscribing sub_id=#{sub_id} client_pubkey=#{@connection_string.client_pubkey} wallet_pubkey=#{@connection_string.wallet_pubkey} kinds=#{kinds.inspect} since=#{since}")
+        @logger.info(
+          "[nwc] subscribing sub_id=#{sub_id} client_pubkey=#{@connection_string.client_pubkey} " \
+          "wallet_pubkey=#{@connection_string.wallet_pubkey} kinds=#{kinds.inspect} since=#{since}"
+        )
         c.send_req(sub_id: sub_id, filters: filters)
       end
 

data/lib/nwc_ruby/test_runner.rb

@@ -56,8 +56,8 @@ module NwcRuby
 
       if @pay_to_lightning_address
         if @info.read_only?
-          warn!("pay_to_lightning_address was provided but this is a READ-ONLY code — it does not support pay_invoice.")
-          warn!("  → Generate a read+write NWC code if you need to test outbound payments.")
+          warn!('pay_to_lightning_address was provided but this is a READ-ONLY code — it does not support pay_invoice.')
+          warn!('  → Generate a read+write NWC code if you need to test outbound payments.')
           @out.puts
         else
           run_write_tests
@@ -205,7 +205,10 @@ module NwcRuby
         try('lookup_invoice (payment_hash from previous step)', NIP47::Methods::LOOKUP_INVOICE) do
           result = @client.lookup_invoice(payment_hash: @test_payment_hash)
           @out.puts "    #{DIM}state=#{result['state']} amount=#{result['amount']} msats#{CLR}"
-          warn!("lookup_invoice: `state` is #{result['state'].inspect}, expected 'pending' for a fresh invoice (optional per NIP-47)") unless result['state'] == 'pending'
+          unless result['state'] == 'pending'
+            warn!("lookup_invoice: `state` is #{result['state'].inspect}, " \
+                  "expected 'pending' for a fresh invoice (optional per NIP-47)")
+          end
         end
       end
 
@@ -252,8 +255,12 @@ module NwcRuby
         fail!('make_invoice: `payment_hash` is not a 64-char hex')
       end
       fail!('make_invoice: `amount` should echo 1000') unless result['amount'] == 1_000
-      warn!("make_invoice: `type` is #{result['type'].inspect}, expected 'incoming' (optional per NIP-47)") unless result['type'] == 'incoming'
-      warn!("make_invoice: `state` is #{result['state'].inspect}, expected 'pending' (optional per NIP-47)") unless result['state'] == 'pending'
+      unless result['type'] == 'incoming'
+        warn!("make_invoice: `type` is #{result['type'].inspect}, expected 'incoming' (optional per NIP-47)")
+      end
+      return if result['state'] == 'pending'
+
+      warn!("make_invoice: `state` is #{result['state'].inspect}, expected 'pending' (optional per NIP-47)")
     end
 
     # --- Lightning address resolver ----------------------------------------

data/lib/nwc_ruby/transport/relay_connection.rb

@@ -63,14 +63,19 @@ module NwcRuby
 
       def stop!
         @stop = true
-        # Close the websocket to unblock the read loop. The @stop flag
-        # will cause the run loop to exit on its own. We avoid calling
-        # @top_task.stop here because stop! may be called from a
-        # different thread than the Async reactor.
-        begin
-          @conn&.close
-        rescue StandardError
-          nil
+        # Poke the signal pipe if available (works from any thread); the
+        # watcher task will call @top_task.stop from inside the reactor.
+        # If we're already inside the reactor thread/fiber, we can stop
+        # the top task directly.
+        if @signal_pipe_w
+          begin
+            @signal_pipe_w.write_nonblock('.')
+          rescue IO::WaitWritable, Errno::EPIPE, IOError
+            nil
+          end
+        else
+          task = @top_task
+          task&.stop
         end
       end
 
@@ -82,10 +87,15 @@ module NwcRuby
 
         Async do |top|
           @top_task = top
+          signal_watcher = start_signal_watcher(top)
           until @stop
             begin
               run_one_connection(top)
               backoff = 1
+            rescue Interrupt, Async::Stop
+              # Ctrl-C / SIGTERM / task.stop: exit cleanly.
+              @stop = true
+              break
             rescue StandardError => e
               break if @stop
 
@@ -97,7 +107,12 @@ module NwcRuby
               backoff *= 2
             end
           end
+        rescue Interrupt
+          # Signal arrived while not inside a connection; just exit.
+          @stop = true
         ensure
+          signal_watcher&.stop
+          close_signal_pipe
           @top_task = nil
         end
       end
@@ -135,39 +150,8 @@ module NwcRuby
 
         Async::WebSocket::Client.connect(endpoint) do |conn|
           @conn = conn
-
-          heartbeat = top.async do
-            loop do
-              conn.send_ping
-              conn.flush
-              @logger.debug("[nwc] ping sent")
-
-              sleep @ping_interval
-              break if @stop
-
-              if Async::Clock.now - opened_at > @recycle_interval
-                raise TransportError, "recycle (#{@recycle_interval}s)"
-              end
-            end
-          end
-
-          # Some relays (e.g. strfry) store ephemeral events temporarily but
-          # do not push them to active subscriptions. Periodic re-subscribe
-          # forces the relay to return any newly-stored events.
-          poll = if @poll_interval && @poll_cb
-                   top.async do
-                     loop do
-                       sleep @poll_interval
-                       break if @stop
-
-                       begin
-                         @poll_cb.call(self)
-                       rescue StandardError => e
-                         @logger.warn("[nwc] poll error: #{e.message}")
-                       end
-                     end
-                   end
-                 end
+          heartbeat = start_heartbeat(top, conn, opened_at)
+          poll      = start_poll(top)
 
           @open_cb&.call(self)
           read_loop(conn)
@@ -183,6 +167,38 @@ module NwcRuby
         end
       end
 
+      def start_heartbeat(top, conn, opened_at)
+        top.async do
+          loop do
+            conn.send_ping
+            conn.flush
+            @logger.debug('[nwc] ping sent')
+
+            sleep @ping_interval
+            break if @stop
+
+            raise TransportError, "recycle (#{@recycle_interval}s)" if Async::Clock.now - opened_at > @recycle_interval
+          end
+        end
+      end
+
+      def start_poll(top)
+        return unless @poll_interval && @poll_cb
+
+        top.async do
+          loop do
+            sleep @poll_interval
+            break if @stop
+
+            begin
+              @poll_cb.call(self)
+            rescue StandardError => e
+              @logger.warn("[nwc] poll error: #{e.message}")
+            end
+          end
+        end
+      end
+
       def read_loop(conn)
         while (message = conn.read)
           break if @stop
@@ -218,18 +234,51 @@ module NwcRuby
       end
 
       def install_traps
+        # Keep signal handlers tiny. We can't do much from inside a Ruby
+        # signal handler:
+        #   - SSL I/O / socket close can deadlock.
+        #   - Async::Task#stop takes a Mutex, which raises
+        #     "can't be called from trap context (ThreadError)".
+        #   - Thread.new { task.stop } runs outside the reactor and
+        #     Fiber.scheduler is nil there.
+        # So: flip a flag and poke a self-pipe. An Async task watches the
+        # read end of the pipe and calls @top_task.stop from inside the
+        # reactor, which is the only safe place to do it.
+        @signal_pipe_r, @signal_pipe_w = IO.pipe
         %w[TERM INT].each do |sig|
           trap(sig) do
             @stop = true
-            # Close the socket to unblock the read loop.
             begin
-              @conn&.close
-            rescue StandardError # rubocop:disable Lint/SuppressedException
+              @signal_pipe_w.write_nonblock('.')
+            rescue IO::WaitWritable, Errno::EPIPE, IOError
+              nil
             end
           end
         end
       end
 
+      def start_signal_watcher(top)
+        return unless @signal_pipe_r
+
+        top.async do
+          @signal_pipe_r.read(1)
+          @logger.debug('[nwc] signal received, stopping')
+          top.stop
+        rescue IOError, Errno::EBADF
+          nil
+        end
+      end
+
+      def close_signal_pipe
+        [@signal_pipe_r, @signal_pipe_w].each do |io|
+          io&.close
+        rescue IOError
+          nil
+        end
+        @signal_pipe_r = nil
+        @signal_pipe_w = nil
+      end
+
       def default_logger
         logger = Logger.new($stdout)
         logger.level = ENV['NWC_LOG_LEVEL'] ? Logger.const_get(ENV['NWC_LOG_LEVEL'].upcase) : Logger::INFO

data/lib/nwc_ruby/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nwc-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - MegalithicBTC
@@ -222,7 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.6.8
 specification_version: 4
 summary: Ruby client for Nostr Wallet Connect (NIP-47) with safe long-running relay
   connections.