strelka 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a69b39669c90e69f7ea690787d47981776c6a29044febf339d8890c240d6d1aa
-  data.tar.gz: 0bc16e15b5a1196a3944b99156eae5039eb8d9f7a5e71636974c41b7853f5fd2
+  metadata.gz: 7dad453a5871872ca4f793e78253510d82e4ed27fbb173c82629501c60962477
+  data.tar.gz: 8bf1feafca4c80397808322ed09c93b9c6ed56cd917c5db12ab0f1e33cf8a59f
 SHA512:
-  metadata.gz: bb4c71d572c432b6a13a6b66ab4a1060c45f0d326bff9a4841579a30d2dd55b2782662252a28d22195bf228651aa5a8ea225295a846000f874a6c2cb38ab6c9e
-  data.tar.gz: 9ae69ea8b0aadd5ae2567084641f7114cbf99089e7394b5e7dcd8438145f8a92570820d2b2b5bb457bb3f859b3334b82f2923eb205dba9d35f19d39c168432bc
+  metadata.gz: a220e3f1d3f6fdaf963173170dc2186ebf580a2b93c522017df7cfd7ba3ef3d45850943552a510e7bacbed11271dca7d0a42f1349b74651c64c5a9a957f852f5
+  data.tar.gz: b8eb408709e9fb4269d0516236d9d203a4ea3e59580b82c9b8d9939d7932c6722d79f0076aa44fd08638ce890dc7c6270e4c772ed9b064d698e043055596078e

data/Manifest.txt

@@ -73,6 +73,7 @@ lib/strelka/httpresponse/negotiation.rb
 lib/strelka/httpresponse/session.rb
 lib/strelka/mixins.rb
 lib/strelka/multipartparser.rb
+lib/strelka/multirunner.rb
 lib/strelka/paramvalidator.rb
 lib/strelka/plugins.rb
 lib/strelka/router.rb
@@ -81,6 +82,7 @@ lib/strelka/router/exclusive.rb
 lib/strelka/session.rb
 lib/strelka/session/db.rb
 lib/strelka/session/default.rb
+lib/strelka/signal_handling.rb
 lib/strelka/testing.rb
 lib/strelka/websocketserver.rb
 lib/strelka/websocketserver/heartbeat.rb

data/lib/strelka.rb

@@ -22,7 +22,7 @@ module Strelka
 	extend Loggability
 
 	# Library version constant
-	VERSION = '0.17.0'
+	VERSION = '0.18.0'
 
 	# Version-control revision constant
 	REVISION = %q$Revision$
@@ -77,6 +77,11 @@ module Strelka
 	singleton_attr_reader :after_configure_hooks
 	@after_configure_hooks = Set.new
 
+	##
+	# An Array of callbacks to be run before forking a handler process
+	singleton_attr_reader :before_fork_hooks
+	@before_fork_hooks = Set.new
+
 	##
 	# True if the after_configure hooks have already (started to) run.
 	singleton_predicate_reader :after_configure_hooks_run
@@ -123,6 +128,25 @@ module Strelka
 	end
 
 
+	### Call the before-fork hooks.
+	def self::call_before_fork_hooks
+		self.log.debug "  calling %d before-fork hooks" % [ self.before_fork_hooks.length ]
+
+		self.before_fork_hooks.to_a.each do |hook|
+			self.log.debug "    %s line %s..." % hook.source_location
+			hook.call
+		end
+	end
+
+
+	### Register a callback to be run before forking a Strelka::Handler
+	### subprocess.
+	def self::before_fork( &block )
+		raise LocalJumpError, "no block given" unless block
+		self.before_fork_hooks << block
+	end
+
+
 	### Load the specified +config_file+, install the config in all objects with
 	### Configurability, and call any callbacks registered via #after_configure.
 	def self::load_config( config_file=nil, defaults=nil )

data/lib/strelka/command/start.rb

@@ -3,6 +3,7 @@
 # frozen-string-literal: true
 
 require 'strelka/cli' unless defined?( Strelka::CLI )
+require 'strelka/multirunner'
 
 
 # Command to start a Strelka application
@@ -51,8 +52,7 @@ module Strelka::CLI::Start
 				if options.number == 1
 					app.run
 				else
-					options.number.times { fork { app.run } }
-					Process.waitall
+					Strelka::MultiRunner.new( app, options.number ).run
 				end
 			end
 		end

data/lib/strelka/multirunner.rb

@@ -0,0 +1,123 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# frozen-string-literal: true
+
+require 'strelka' unless defined?( Strelka )
+require 'strelka/signal_handling'
+
+# Load multiple simulatneous Strelka handlers (of a single type) with
+# proper signal handling.
+#
+class Strelka::MultiRunner
+	extend Loggability
+	include Strelka::SignalHandling
+
+	# Loggability API -- set up logging under the 'strelka' log host
+	log_to :strelka
+
+
+	# Signals we understand.
+	QUEUE_SIGS = [ :QUIT, :INT, :TERM, :CHLD ]
+
+
+	### Create a new multirunner instance given a handler +app_class+,
+	### and the +number+ of instances to start.
+	def initialize( app_class, number=2 )
+		@handler_pids = []
+		@running      = false
+		@app_class    = app_class
+		@number       = number
+
+		self.set_up_signal_handling
+	end
+
+	# The child handler pids.
+	attr_reader :handler_pids
+
+	# In this instance currently managing children?
+	attr_reader :running
+
+	# How many handler children to manage.
+	attr_reader :number
+
+	# The class name of the handler.
+	attr_reader :app_class
+
+
+	### Start the child handlers via fork(), block for signals.
+	def run
+		@running = true
+
+		# Set up traps for common signals
+		self.set_signal_traps( *QUEUE_SIGS )
+
+		self.log.debug "Starting multirunner loop..."
+		self.spawn_children
+		self.wait_for_signals while self.running
+		self.log.debug "Ending multirunner."
+
+		# Restore the default signal handlers
+		self.reset_signal_traps( *QUEUE_SIGS )
+
+		return
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Start the handlers using fork().
+	def spawn_children
+		self.number.times do
+			Strelka.call_before_fork_hooks
+			pid = Process.fork do
+				Process.setpgrp
+				self.app_class.run
+			end
+			self.handler_pids << pid
+			Process.setpgid( pid, 0 )
+		end
+	end
+
+
+	### Wait on the child associated with the given +pid+, deleting it from the
+	### running tasks Hash if successful.
+	def reap_children( signal )
+		self.handler_pids.dup.each do |pid|
+			self.log.debug "  sending %p to pid %p" % [ signal, pid ]
+			Process.kill( signal, pid )
+			pid, status = Process.waitpid2( pid, Process::WUNTRACED )
+			self.log.debug "  waitpid2 returned: [ %p, %p ]" % [ pid, status ]
+			self.handler_pids.delete( pid )
+		end
+	end
+
+
+	### Handle signals.
+	def handle_signal( sig )
+		self.log.debug "Handling signal %s in PID %d" % [ sig, Process.pid ]
+		case sig
+		when :INT, :TERM, :QUIT
+			if @running
+				self.log.warn "%s signal: graceful shutdown" % [ sig ]
+				self.reap_children( sig )
+				@running = false
+			else
+				self.ignore_signals
+				self.log.warn "%s signal: forceful shutdown" % [ sig ]
+				self.kill_children( :KILL )
+				exit!( 255 )
+			end
+
+		when :CHLD
+			self.log.info "Got SIGCHLD."
+			# Just need to wake up, nothing else necessary
+
+		else
+			self.log.warn "Unhandled signal %s" % [ sig ]
+		end
+	end
+
+end # class Strelka::MultiRunner
+

data/lib/strelka/signal_handling.rb

@@ -0,0 +1,117 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'strelka'
+
+
+# A module containing signal-handling logic for the 'start' command
+# line.
+module Strelka::SignalHandling
+
+	### Wrap a block in signal-handling.
+	def with_signal_handler( *signals )
+		self.set_up_signal_handling
+		self.set_signal_traps( *signals )
+		self.start_signal_handler
+
+		return yield
+
+	ensure
+		self.stop_signal_handler
+		self.reset_signal_traps( *signals )
+	end
+
+
+	### Set up data structures for signal handling.
+	def set_up_signal_handling
+		# Self-pipe for deferred signal-handling (ala djb:
+		# http://cr.yp.to/docs/selfpipe.html)
+		reader, writer       = IO.pipe
+		reader.close_on_exec = true
+		writer.close_on_exec = true
+		@selfpipe            = { reader: reader, writer: writer }
+
+		# Set up a global signal queue
+		Thread.main[:signal_queue] = []
+	end
+
+
+	### The body of the signal handler. Wait for at least one signal to arrive and
+	### handle it, or timeout and return if a +timeout+ integer is provided.  This
+	### should be called inside a loop, either in its own thread or in another loop
+	### that doesn't block anywhere else.  Returns true if a signal was handled, or
+	### false if a timeout occurred.
+	def wait_for_signals( timeout=nil )
+
+		# Wait on the selfpipe for signals
+		# self.log.debug "  waiting for the selfpipe"
+		fds = IO.select( [@selfpipe[:reader]], [], [], timeout )
+		begin
+			rval = @selfpipe[:reader].read_nonblock( 11 )
+			self.log.debug "    read from the selfpipe: %p" % [ rval ]
+		rescue Errno::EAGAIN, Errno::EINTR => err
+			# ignore
+		end
+
+		# Look for any signals that arrived and handle them
+		while sig = Thread.main[:signal_queue].shift
+			self.log.debug "  got a queued signal: %p" % [ sig ]
+			self.handle_signal( sig )
+		end
+
+		return fds ? true : false
+	end
+
+
+	### Wake the main thread up through the self-pipe.
+	### Note: since this is a signal-handler method, it needs to be re-entrant.
+	def wake_up
+		@selfpipe[:writer].write_nonblock('.')
+	rescue Errno::EAGAIN
+		# Ignore.
+	rescue Errno::EINTR
+		# Repeated signal. :TODO: Does this need a counter?
+		retry
+	end
+
+
+	### Set up signal handlers for common signals that will shut down, restart, etc.
+	def set_signal_traps( *signals )
+		self.log.debug "Setting up deferred signal handlers."
+		signals.each do |sig|
+			Signal.trap( sig ) do
+				Thread.main[:signal_queue] << sig
+				self.wake_up
+			end
+		end
+	end
+
+
+	### Set all signal handlers to ignore.
+	def ignore_signals( *signals )
+		self.log.debug "Ignoring signals."
+		signals.each do |sig|
+			next if sig == :CHLD
+			Signal.trap( sig, :IGNORE )
+		end
+	end
+
+
+	### Set the signal handlers back to their defaults.
+	def reset_signal_traps( *signals )
+		self.log.debug "Restoring default signal handlers."
+		signals.each do |sig|
+			Signal.trap( sig, :DEFAULT )
+		end
+	end
+
+
+	### Simulate the receipt of the specified +signal+ (probably only useful
+	### in testing).
+	def simulate_signal( signal )
+		Thread.main[:signal_queue] << signal.to_sym
+		self.wake_up
+	end
+
+end # module Strelka::SignalHandling
+

data/spec/strelka_spec.rb

@@ -189,5 +189,19 @@ RSpec.describe Strelka do
 	end
 
 
+	it "provides a way to register blocks that should run before a fork" do
+		callback_ran = false
+		Strelka.before_fork { callback_ran = true }
+		Strelka.call_before_fork_hooks
+
+		expect( callback_ran ).to be( true )
+	end
+
+	it "raises an exception if .before_fork is called without a block" do
+		expect {
+			Strelka.before_fork
+		}.to raise_error( LocalJumpError, /no block given/i )
+	end
+
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strelka
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Mahlon E. Smith
@@ -35,7 +35,7 @@ cert_chain:
   g3nSb5geweeDxf7Phf3qyZgglWB4UGR0aUkzOwj6yFj1ugCU2R7CwNhqgmtdkvYm
   tuLuv1oCfpuEmRh93FiLFsOLV3auiU+c
   -----END CERTIFICATE-----
-date: 2019-09-18 00:00:00.000000000 Z
+date: 2019-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: configurability
@@ -408,6 +408,7 @@ files:
 - lib/strelka/httpresponse/session.rb
 - lib/strelka/mixins.rb
 - lib/strelka/multipartparser.rb
+- lib/strelka/multirunner.rb
 - lib/strelka/paramvalidator.rb
 - lib/strelka/plugins.rb
 - lib/strelka/router.rb
@@ -416,6 +417,7 @@ files:
 - lib/strelka/session.rb
 - lib/strelka/session/db.rb
 - lib/strelka/session/default.rb
+- lib/strelka/signal_handling.rb
 - lib/strelka/testing.rb
 - lib/strelka/websocketserver.rb
 - lib/strelka/websocketserver/heartbeat.rb