Add graceful default signal handlers. (#4)

Author: samuel-williams-shopify

lib/async/signals/graceful.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module Signals
+		# Installs default signal handlers for graceful shutdown.
+		#
+		# Ruby's built-in handling for `SIGINT` can bypass `Thread.handle_interrupt`, which makes graceful shutdown unreliable for event loops and other code that needs to defer interruption while cleaning up. This file also maps `SIGTERM` to `Interrupt`, so both termination signals follow the same graceful shutdown path when they are still using Ruby's default handler.
+		#
+		# See <https://bugs.ruby-lang.org/issues/22133> for more details.
+		module Graceful
+			SIGNALS = ["INT", "TERM"].freeze
+			
+			SIGNALS.each do |signal|
+				previous = ::Signal.trap(signal) do
+					::Thread.main.raise(::Interrupt)
+				end
+				
+				unless previous == "DEFAULT"
+					::Signal.trap(signal, previous)
+				end
+			end
+		end
+	end
+end

releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## Unreleased
+
+  - Add `async/signals/graceful` for installing default `SIGINT` and `SIGTERM` handlers that raise `Interrupt`.
+
 ## v0.5.0
 
   - Change `Async::Signals.default` to select process signal handling only on the main thread when no fiber scheduler is installed.

test/async/signals/graceful.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "open3"
+require "rbconfig"
+
+describe "Async::Signals::Graceful" do
+	def ruby(script)
+		::Open3.capture3(::RbConfig.ruby, "-Ilib", "-e", script)
+	end
+	
+	def expect_success(script)
+		stdout, stderr, status = ruby(script)
+		
+		expect(status).to be(:success?)
+		expect(stderr).to be == ""
+		
+		stdout
+	end
+	
+	it "installs graceful SIGINT handling" do
+		stdout = expect_success(<<~RUBY)
+			require "async/signals/graceful"
+			
+			begin
+				::Thread.handle_interrupt(::Interrupt => :never) do
+					::Process.kill(:INT, ::Process.pid)
+					puts "inner"
+				end
+				
+				sleep 1
+			rescue ::Interrupt
+				puts "outer"
+			end
+		RUBY
+		
+		expect(stdout).to be == "inner\nouter\n"
+	end
+	
+	it "installs graceful SIGTERM handling" do
+		stdout = expect_success(<<~RUBY)
+			require "async/signals/graceful"
+			
+			begin
+				::Thread.handle_interrupt(::Interrupt => :never) do
+					::Process.kill(:TERM, ::Process.pid)
+					puts "inner"
+				end
+				
+				sleep 1
+			rescue ::Interrupt
+				puts "outer"
+			end
+		RUBY
+		
+		expect(stdout).to be == "inner\nouter\n"
+	end
+	
+	it "preserves existing SIGINT handlers" do
+		stdout = expect_success(<<~RUBY)
+			events = ::Thread::Queue.new
+			
+			::Signal.trap(:INT) do
+				events << "handled"
+			end
+			
+			require "async/signals/graceful"
+			
+			::Process.kill(:INT, ::Process.pid)
+			
+			puts events.pop(timeout: 1)
+		RUBY
+		
+		expect(stdout).to be == "handled\n"
+	end
+	
+	it "preserves existing SIGTERM handlers" do
+		stdout = expect_success(<<~RUBY)
+			events = ::Thread::Queue.new
+			
+			::Signal.trap(:TERM) do
+				events << "handled"
+			end
+			
+			require "async/signals/graceful"
+			
+			::Process.kill(:TERM, ::Process.pid)
+			
+			puts events.pop(timeout: 1)
+		RUBY
+		
+		expect(stdout).to be == "handled\n"
+	end
+end