Implement simple lifecycle hooks for the supervisor on start and stop

And document those in the README.

Author: rosa

README.md

@@ -208,6 +208,18 @@ Finally, run the migrations:
 $ bin/rails db:migrate
 ```
 
+## Supervisor's lifecycle hooks
+You can hook into two different points in the supervisor's life in Solid Queue:
+- `start`: after the supervisor has finished booting and right before it forks workers and dispatchers.
+- `stop`: after receiving a signal (`TERM`, `INT` or `QUIT`) and right before starting graceful or immediate shutdown.
+
+To do that, you just need to call `SolidQueue.on_start` and `SolidQueue.on_stop` with a block, like this:
+```ruby
+SolidQueue.on_start { start_metrics_server }
+SolidQueue.on_stop { stop_metrics_server }
+```
+
+
 ### Other configuration settings
 _Note_: The settings in this section should be set in your `config/application.rb` or your environment config like this: `config.solid_queue.silence_polling = true`
 

lib/solid_queue.rb

@@ -43,6 +43,8 @@ module SolidQueue
   mattr_accessor :clear_finished_jobs_after, default: 1.day
   mattr_accessor :default_concurrency_control_period, default: 3.minutes
 
+  delegate :on_start, :on_stop, to: Supervisor
+
   def supervisor?
     supervisor
   end

lib/solid_queue/supervisor.rb

@@ -2,7 +2,7 @@
 
 module SolidQueue
   class Supervisor < Processes::Base
-    include Maintenance, Signals, Pidfiled
+    include Maintenance, LifecycleHooks, Signals, Pidfiled
 
     class << self
       def start(load_configuration_from: nil)
@@ -27,6 +27,7 @@ def initialize(configuration)
 
     def start
       boot
+      run_start_hooks
 
       start_processes
       launch_maintenance_task
@@ -36,6 +37,7 @@ def start
 
     def stop
       @stopped = true
+      run_stop_hooks
     end
 
     private

lib/solid_queue/supervisor/lifecycle_hooks.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SolidQueue
+  class Supervisor
+    module LifecycleHooks
+      extend ActiveSupport::Concern
+
+      included do
+        mattr_reader :lifecycle_hooks, default: { start: [], stop: [] }
+      end
+
+      class_methods do
+        def on_start(&block)
+          self.lifecycle_hooks[:start] << block
+        end
+
+        def on_stop(&block)
+          self.lifecycle_hooks[:stop] << block
+        end
+
+        def clear_hooks
+          self.lifecycle_hooks[:start] = []
+          self.lifecycle_hooks[:stop] = []
+        end
+      end
+
+      private
+        def run_start_hooks
+          run_hooks_for :start
+        end
+
+        def run_stop_hooks
+          run_hooks_for :stop
+        end
+
+        def run_hooks_for(event)
+          self.class.lifecycle_hooks.fetch(event, []).each do |block|
+            block.call
+          rescue Exception => exception
+            handle_thread_error(exception)
+          end
+        end
+    end
+  end
+end

test/unit/supervisor_test.rb

@@ -128,6 +128,43 @@ class SupervisorTest < ActiveSupport::TestCase
     end
   end
 
+  test "run lifecycle hooks" do
+    SolidQueue.on_start { JobResult.create!(status: :hook_called, value: :start) }
+    SolidQueue.on_stop { JobResult.create!(status: :hook_called, value: :stop) }
+
+    pid = run_supervisor_as_fork
+    wait_for_registered_processes(4)
+
+    terminate_process(pid)
+    wait_for_registered_processes(0)
+
+    results = skip_active_record_query_cache { JobResult.last(2) }
+
+    assert_equal "hook_called", results.map(&:status).first
+    assert_equal [ "start", "stop" ], results.map(&:value)
+  ensure
+    SolidQueue::Supervisor.clear_hooks
+  end
+
+  test "handle errors on lifecycle hooks" do
+    previous_on_thread_error, SolidQueue.on_thread_error = SolidQueue.on_thread_error, ->(error) { JobResult.create!(status: :error, value: error.message) }
+    SolidQueue.on_start { raise RuntimeError, "everything is broken" }
+
+    pid = run_supervisor_as_fork
+    wait_for_registered_processes(4)
+
+    terminate_process(pid)
+    wait_for_registered_processes(0)
+
+    result = skip_active_record_query_cache { JobResult.last }
+
+    assert_equal "error", result.status
+    assert_equal "everything is broken", result.value
+  ensure
+    SolidQueue.on_thread_error = previous_on_thread_error
+    SolidQueue::Supervisor.clear_hooks
+  end
+
   private
     def assert_registered_workers(supervisor_pid: nil, count: 1)
       assert_registered_processes(kind: "Worker", count: count, supervisor_pid: supervisor_pid)