nwc-ruby 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5d73701179764ad26d1ad95d212e1abd5856788a951591e3f8489b16e66d0f0
-  data.tar.gz: 97047cb484ab707715cd0ce4590d356a9b0e23a307729c808f0098f043c94dba
+  metadata.gz: d541ad9af31629ad26492d8da61d56b0a63980cc8597a460cca9949df56f382d
+  data.tar.gz: 8d48fbbe532bdcf56d889f68f9d7878fa2958381c1ea285fb572aebb70d17d7e
 SHA512:
-  metadata.gz: f7bfd6655a81a49a9c04e534a872be4be1438af498b77f452a14706feb8535b9421745cc4f15c488339532019e1f94fb0b56d14c55a565b440f6232fea067b74
-  data.tar.gz: 8af52b0b23683c1c62e0d64f4c02597c82c9aa64ae277da7d7099208453ba596db58b3762abdb728a08c2d063013befc39f8c699c39ce4e66aa921c77e90a839
+  metadata.gz: bbc5e4a3efdac9b24a4a2c5fc183f3945ba9987fd5312c78a7e8c4ba8cff625af5c08521094cc10101fd24a0bef5f35261eb29720d533d7e0167a236ee59d106
+  data.tar.gz: fb2c7a1ed8d7785a886b38e250432466354b257cef1e4c8552ef24c493c304dbd446bf4c17e57debcce8bc6875666686c16f901d29474ef08541194e6e2a97f3

data/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Silenced the noisy `Async::Task` warn log ("Task may have ended with
+  unhandled exception") that was emitted every `recycle_interval` (default
+  5 min) by the heartbeat task. The forced recycle used to be signaled by
+  raising `TransportError` from inside the heartbeat's child Async task; the
+  parent's reconnect loop caught it correctly, but Async's console logger
+  logged the unhandled-in-child exception with a full backtrace first.
+  The recycle is now signaled by setting an `@recycle_requested` flag and
+  closing the websocket, which unblocks the read loop and lets
+  `run_one_connection` return normally without any exception crossing a task
+  boundary.
+
+## [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

data/README.md

@@ -2,6 +2,14 @@
 
 A production-grade Ruby client for [Nostr Wallet Connect (NIP-47)][nip47].
 
+Accept and track Bitcoin Lightning payments in your Rails app without running
+any Lightning infrastructure yourself. Generate Lightning invoices for your
+users to pay, then get notified the instant each one settles — all by talking
+to a Nostr Wallet Connect (NWC) service that someone else operates. The gem
+works with any NWC-compatible backend (Rizful, Alby Hub, Alby Cloud, CoinOs,
+any NIP-47 wallet service), so you're not locked into a single provider and
+can swap vendors by changing one environment variable.
+
 ```ruby
 require "nwc_ruby"
 

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
@@ -131,6 +146,7 @@ module NwcRuby
       def run_one_connection(top)
         endpoint  = Async::HTTP::Endpoint.parse(@url, alpn_protocols: ['http/1.1'])
         opened_at = Async::Clock.now
+        @recycle_requested = false
         @logger.info("[nwc] connecting to #{@url}")
 
         Async::WebSocket::Client.connect(endpoint) do |conn|
@@ -140,6 +156,7 @@ module NwcRuby
 
           @open_cb&.call(self)
           read_loop(conn)
+          @logger.info("[nwc] recycling connection (#{@recycle_interval}s)") if @recycle_requested
         ensure
           heartbeat&.stop
           poll&.stop
@@ -152,6 +169,13 @@ module NwcRuby
         end
       end
 
+      # Heartbeat task: sends RFC 6455 ping every @ping_interval seconds and
+      # requests a recycle once the connection has been open longer than
+      # @recycle_interval. The recycle is signaled via a flag + close rather
+      # than by raising across task boundaries, because an exception raised
+      # inside a child Async task is logged at warn level by Async's console
+      # logger ("Task may have ended with unhandled exception") before the
+      # parent's rescue runs — producing a noisy backtrace on every recycle.
       def start_heartbeat(top, conn, opened_at)
         top.async do
           loop do
@@ -161,12 +185,25 @@ module NwcRuby
 
             sleep @ping_interval
             break if @stop
-
-            raise TransportError, "recycle (#{@recycle_interval}s)" if Async::Clock.now - opened_at > @recycle_interval
+            break if recycle_due?(opened_at) && request_recycle(conn)
           end
         end
       end
 
+      def recycle_due?(opened_at)
+        Async::Clock.now - opened_at > @recycle_interval
+      end
+
+      def request_recycle(conn)
+        @recycle_requested = true
+        begin
+          conn.close
+        rescue StandardError
+          nil
+        end
+        true
+      end
+
       def start_poll(top)
         return unless @poll_interval && @poll_cb
 
@@ -185,7 +222,21 @@ module NwcRuby
       end
 
       def read_loop(conn)
-        while (message = conn.read)
+        loop do
+          message =
+            begin
+              conn.read
+            rescue StandardError => e
+              # If we asked for the recycle/close ourselves, treat the
+              # resulting read error as a clean EOF rather than propagating
+              # it up into the reconnect-on-error path (which would log a
+              # spurious warning).
+              raise unless @recycle_requested || @stop
+
+              @logger.debug("[nwc] read interrupted by close: #{e.class}")
+              nil
+            end
+          break if message.nil?
           break if @stop
 
           begin
@@ -219,19 +270,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
+              @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.1'
+  VERSION = '0.2.3'
 end

metadata

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