SIGTERM is now graceful, the same as SIGINT. (#50)

Author: samuel-williams-shopify

context/kubernetes-integration.md

@@ -37,3 +37,9 @@ spec:
             periodSeconds: 5
             failureThreshold: 12
 ```
+
+## Graceful Shutdown
+
+Controllers handle `SIGTERM` gracefully (same as `SIGINT`). This ensures proper graceful shutdown when Kubernetes terminates pods during rolling updates, scaling down, or pod eviction.
+
+**Note**: Kubernetes sends `SIGTERM` to containers when terminating pods. With graceful handling, your application will have time to clean up resources, finish in-flight requests, and shut down gracefully before Kubernetes sends `SIGKILL` (after the termination grace period).

context/systemd-integration.md

@@ -20,3 +20,9 @@ WantedBy=multi-user.target
 ```
 
 Ensure `Type=notify` is set, so that the service can notify systemd when it is ready.
+
+## Graceful Shutdown
+
+Controllers handle `SIGTERM` gracefully (same as `SIGINT`). This ensures proper graceful shutdown when systemd stops the service.
+
+**Note**: systemd sends `SIGTERM` to services when stopping them. With graceful handling, your application will have time to clean up resources, finish in-flight requests, and shut down gracefully before systemd escalates to `SIGKILL` (after the timeout specified in the service file).

fixtures/async/container/controllers/graceful.rb

@@ -12,34 +12,19 @@ class Graceful < Async::Container::Controller
 	def setup(container)
 		container.run(name: "graceful", count: 1, restart: true) do |instance|
 			instance.ready!
-			
-			# This is to avoid race conditions in the controller in test conditions.
-			sleep 0.001
-			
-			clock = Async::Clock.start
-			
-			original_action = Signal.trap(:INT) do
-				# We ignore the int, but in practical applications you would want start a graceful shutdown.
-				$stdout.puts "Graceful shutdown...", clock.total
-				
-				Signal.trap(:INT, original_action)
-			end
-			
-			$stdout.puts "Ready...", clock.total
+			$stdout.puts "Ready..."
 
 			sleep
 		ensure
-			$stdout.puts "Exiting...", clock.total
+			$stdout.puts "Exiting..."
 		end
 	end
 end
 
-controller = Graceful.new(graceful_stop: 0.01)
+controller = Graceful.new
 
 begin
 	controller.run
-rescue Async::Container::Terminate
-	$stdout.puts "Terminated..."
 rescue Interrupt
 	$stdout.puts "Interrupted..."
 end

guides/kubernetes-integration/readme.md

@@ -37,3 +37,9 @@ spec:
             periodSeconds: 5
             failureThreshold: 12
 ```
+
+## Graceful Shutdown
+
+Controllers handle `SIGTERM` gracefully (same as `SIGINT`). This ensures proper graceful shutdown when Kubernetes terminates pods during rolling updates, scaling down, or pod eviction.
+
+**Note**: Kubernetes sends `SIGTERM` to containers when terminating pods. With graceful handling, your application will have time to clean up resources, finish in-flight requests, and shut down gracefully before Kubernetes sends `SIGKILL` (after the termination grace period).

guides/systemd-integration/readme.md

@@ -20,3 +20,9 @@ WantedBy=multi-user.target
 ```
 
 Ensure `Type=notify` is set, so that the service can notify systemd when it is ready.
+
+## Graceful Shutdown
+
+Controllers handle `SIGTERM` gracefully (same as `SIGINT`). This ensures proper graceful shutdown when systemd stops the service.
+
+**Note**: systemd sends `SIGTERM` to services when stopping them. With graceful handling, your application will have time to clean up resources, finish in-flight requests, and shut down gracefully before systemd escalates to `SIGKILL` (after the timeout specified in the service file).

lib/async/container/controller.rb

@@ -134,9 +134,6 @@ def restart
 				if container.failed?
 					@notify&.error!("Container failed to start!")
 
-					Console.info(self, "Stopping failed container...")
-					container.stop(false)
-					
 					raise SetupError, container
 				end
 
@@ -151,9 +148,14 @@ def restart
 				end
 
 				@notify&.ready!(size: @container.size)
+			rescue => error
+				raise
 			ensure
-				# If we are leaving this function with an exception, try to kill the container:
-				container&.stop(false)
+				# If we are leaving this function with an exception, kill the container:
+				if container
+					Console.warn(self, "Stopping failed container...", exception: error)
+					container.stop(false)
+				end
 			end
 
 			# Reload the existing container. Children instances will be reloaded using `SIGHUP`.
@@ -222,9 +224,10 @@ def run
 					::Thread.current.raise(Interrupt)
 				end
 
+				# SIGTERM behaves the same as SIGINT by default.
 				terminate_action = Signal.trap(:TERM) do
-					# $stderr.puts "Received TERM signal, terminating...", caller
-					::Thread.current.raise(Terminate)
+					# $stderr.puts "Received TERM signal, interrupting...", caller
+					::Thread.current.raise(Interrupt)  # Same as SIGINT
 				end
 
 				hangup_action = Signal.trap(:HUP) do

lib/async/container/forked.rb

@@ -102,7 +102,7 @@ def self.fork(**options)
 						::Process.fork do
 							# We use `Thread.current.raise(...)` so that exceptions are filtered through `Thread.handle_interrupt` correctly.
 							Signal.trap(:INT){::Thread.current.raise(Interrupt)}
-							Signal.trap(:TERM){::Thread.current.raise(Terminate)}
+							Signal.trap(:TERM){::Thread.current.raise(Interrupt)}  # Same as SIGINT.
 							Signal.trap(:HUP){::Thread.current.raise(Restart)}
 
 							# This could be a configuration option:

lib/async/container/generic.rb

@@ -126,7 +126,7 @@ def wait_until_ready
 					self.sleep
 
 					if self.status?(:ready)
-						Console.logger.debug(self) do |buffer|
+						Console.debug(self) do |buffer|
 							buffer.puts "All ready:"
 							@state.each do |child, state|
 								buffer.puts "\t#{child.inspect}: #{state}"

lib/async/container/group.rb

@@ -10,11 +10,20 @@
 
 module Async
 	module Container
-		# The default timeout for interrupting processes, before escalating to terminating.
-		INTERRUPT_TIMEOUT = ENV.fetch("ASYNC_CONTAINER_INTERRUPT_TIMEOUT", 10).to_f
-		
 		# The default timeout for terminating processes, before escalating to killing.
-		TERMINATE_TIMEOUT = ENV.fetch("ASYNC_CONTAINER_TERMINATE_TIMEOUT", 10).to_f
+		GRACEFUL_TIMEOUT = ENV.fetch("ASYNC_CONTAINER_GRACEFUL_TIMEOUT", "true").then do |value|
+			case value
+			when "true"
+				true # Default timeout for graceful termination.
+			when "false"
+				false # Immediately kill the processes.
+			else
+				value.to_f
+			end
+		end
+		
+		# The default timeout for graceful termination.
+		DEFAULT_GRACEFUL_TIMEOUT = 10.0
 
 		# Manages a group of running processes.
 		class Group
@@ -155,50 +164,37 @@ def kill
 			# Stop all child processes with a multi-phase shutdown sequence.
 			#
 			# A graceful shutdown performs the following sequence:
-			# 1. Send SIGINT and wait up to `interrupt_timeout` seconds
-			# 2. Send SIGTERM and wait up to `terminate_timeout` seconds  
-			# 3. Send SIGKILL and wait indefinitely for process cleanup
+			# 1. Send SIGINT and wait up to `graceful` seconds if specified.
+			# 2. Send SIGKILL and wait indefinitely for process cleanup.
 			#
-			# If `graceful` is false, skips the SIGINT phase and goes directly to SIGTERM → SIGKILL.
+			# If `graceful` is true, default to `DEFAULT_GRACEFUL_TIMEOUT` (10 seconds).
+			# If `graceful` is false, skip the SIGINT phase and go directly to SIGKILL.
 			#
-			# @parameter graceful [Boolean] Whether to send SIGINT first or skip directly to SIGTERM.
-			# @parameter interrupt_timeout [Numeric | Nil] Time to wait after SIGINT before escalating to SIGTERM.
-			# @parameter terminate_timeout [Numeric | Nil] Time to wait after SIGTERM before escalating to SIGKILL.
-			def stop(graceful = true, interrupt_timeout: INTERRUPT_TIMEOUT, terminate_timeout: TERMINATE_TIMEOUT)
-				case graceful
-				when true
-					# Use defaults.
-				when false
-					interrupt_timeout = nil
-				when Numeric
-					interrupt_timeout = graceful
-					terminate_timeout = graceful
-				end
-				
-				Console.debug(self, "Stopping all processes...", interrupt_timeout: interrupt_timeout, terminate_timeout: terminate_timeout)
+			# @parameter graceful [Boolean | Numeric] Whether to send SIGINT first or skip directly to SIGKILL.
+			def stop(graceful = GRACEFUL_TIMEOUT)
+				Console.info(self, "Stopping all processes...", graceful: graceful)
 
 				# If a timeout is specified, interrupt the children first:
-				if interrupt_timeout
-					clock = Async::Clock.start
-					
-					# Interrupt the children:
+				if graceful
+					# Send SIGINT to the children:
 					self.interrupt
 
-					# Wait for the children to exit:
-					self.wait_for_exit(clock, interrupt_timeout)
-				end
-				
-				if terminate_timeout and self.any?
-					clock = Async::Clock.start
+					if graceful == true
+						graceful = DEFAULT_GRACEFUL_TIMEOUT
+					end
 
-					# If the children are still running, terminate them:
-					self.terminate
+					clock = Clock.start
 
 					# Wait for the children to exit:
-					self.wait_for_exit(clock, terminate_timeout)
+					self.wait_for_exit(clock, graceful)
 				end
-				
+			ensure
+				# Do our best to clean up the children:
 				if any?
+					if graceful
+						Console.warn(self, "Killing processes after graceful shutdown failed...", size: self.size, clock: clock)
+					end
+					
 					self.kill
 					self.wait
 				end

lib/async/container/notify/pipe.rb

@@ -69,7 +69,7 @@ def send(**message)
 					@io.flush
 				end
 
-				private
+			private
 
 				def environment_for(arguments)
 					# Insert or duplicate the environment hash which is the first argument: