Add configurable HTTP health-check server

Author: faraquet

README.md

@@ -28,6 +28,7 @@ Solid Queue can be used with SQL databases such as MySQL, PostgreSQL, or SQLite,
 - [Failed jobs and retries](#failed-jobs-and-retries)
   - [Error reporting on jobs](#error-reporting-on-jobs)
 - [Puma plugin](#puma-plugin)
+- [Health-check HTTP server](#health-check-http-server)
 - [Jobs and transactional integrity](#jobs-and-transactional-integrity)
 - [Recurring tasks](#recurring-tasks)
 - [Inspiration](#inspiration)
@@ -603,6 +604,32 @@ that you set in production only. This is what Rails 8's default Puma config look
 
 **Note**: phased restarts are not supported currently because the plugin requires [app preloading](https://github.com/puma/puma?tab=readme-ov-file#cluster-mode) to work.
 
+## Health-check HTTP server
+
+Solid Queue can start a tiny HTTP server to respond to basic health checks in the same process. This is useful for container orchestrators (e.g. Kubernetes) and external monitoring.
+
+- Endpoints:
+  - `/` and `/health`: returns `200 OK` with body `OK`
+  - Any other path: returns `404 Not Found`
+- Disabled by default. When enabled, defaults are:
+  - host: `ENV["SOLID_QUEUE_HTTP_HOST"]` or `"0.0.0.0"`
+  - port: `ENV["SOLID_QUEUE_HTTP_PORT"]` or `9393`
+
+Enable and configure via `config.solid_queue`:
+
+```ruby
+# config/initializers/solid_queue.rb or config/application.rb
+Rails.application.configure do
+  config.solid_queue.health_server_enabled = true
+  # Optional overrides (defaults already read the env vars above)
+  # config.solid_queue.health_server_host = "0.0.0.0"
+  # config.solid_queue.health_server_port = 9393
+end
+```
+
+Note:
+- When the Puma plugin is active (`plugin :solid_queue` in `puma.rb`), Solid Queue will skip starting the health server even if `health_server_enabled` is set. A warning is logged instead. This prevents running multiple embedded servers in the same process tree.
+
 ## Jobs and transactional integrity
 :warning: Having your jobs in the same ACID-compliant database as your application data enables a powerful yet sharp tool: taking advantage of transactional integrity to ensure some action in your app is not committed unless your job is also committed and vice versa, and ensuring that your job won't be enqueued until the transaction within which you're enqueuing it is committed. This can be very powerful and useful, but it can also backfire if you base some of your logic on this behaviour, and in the future, you move to another active job backend, or if you simply move Solid Queue to its own database, and suddenly the behaviour changes under you. Because this can be quite tricky and many people shouldn't need to worry about it, by default Solid Queue is configured in a different database as the main app.
 

lib/puma/plugin/solid_queue.rb

@@ -13,6 +13,7 @@ def start(launcher)
 
     if Gem::Version.new(Puma::Const::VERSION) < Gem::Version.new("7")
       launcher.events.on_booted do
+        SolidQueue.puma_plugin = true
         @solid_queue_pid = fork do
           Thread.new { monitor_puma }
           SolidQueue::Supervisor.start
@@ -23,6 +24,7 @@ def start(launcher)
       launcher.events.on_restart { stop_solid_queue }
     else
       launcher.events.after_booted do
+        SolidQueue.puma_plugin = true
         @solid_queue_pid = fork do
           Thread.new { monitor_puma }
           SolidQueue::Supervisor.start

lib/solid_queue.rb

@@ -41,6 +41,33 @@ module SolidQueue
   mattr_accessor :clear_finished_jobs_after, default: 1.day
   mattr_accessor :default_concurrency_control_period, default: 3.minutes
 
+  mattr_accessor :health_server_enabled, default: false
+  mattr_accessor :health_server_host,    default: ENV.fetch("SOLID_QUEUE_HTTP_HOST", "0.0.0.0")
+  mattr_accessor :health_server_port,    default: (ENV["SOLID_QUEUE_HTTP_PORT"] || "9393").to_i
+
+  mattr_accessor :puma_plugin, default: false
+
+  def start_health_server
+    return unless health_server_enabled
+
+    if puma_plugin
+      logger.warn("SolidQueue health server is enabled but Puma plugin is active; skipping starting health server to avoid duplicate servers") if logger
+      return nil
+    end
+
+    server = SolidQueue::HealthServer.new(
+      host: health_server_host,
+      port: health_server_port,
+      logger: logger
+    )
+
+    on_start { server.start }
+    on_stop { server.stop }
+    on_exit { server.stop }
+
+    server
+  end
+
   delegate :on_start, :on_stop, :on_exit, to: Supervisor
 
   [ Dispatcher, Scheduler, Worker ].each do |process|

lib/solid_queue/engine.rb

@@ -37,5 +37,11 @@ class Engine < ::Rails::Engine
         include ActiveJob::ConcurrencyControls
       end
     end
+
+    initializer "solid_queue.health_server" do
+      ActiveSupport.on_load(:solid_queue) do
+        SolidQueue.start_health_server
+      end
+    end
   end
 end

lib/solid_queue/health_server.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "socket"
+require "logger"
+
+module SolidQueue
+  class HealthServer
+    def initialize(host:, port:, logger: nil)
+      @host = host
+      @port = port
+      @logger = logger || default_logger
+      @server = nil
+      @thread = nil
+    end
+
+    def start
+      return if running?
+
+      @thread = Thread.new do
+        begin
+          @server = TCPServer.new(@host, @port)
+          log_info("listening on #{@host}:#{@port}")
+
+          loop do
+            socket = @server.accept
+            begin
+              request_line = socket.gets
+              path = request_line&.split(" ")&.at(1) || "/"
+
+              if path == "/" || path == "/health"
+                body = "OK"
+                status_line = "HTTP/1.1 200 OK"
+              else
+                body = "Not Found"
+                status_line = "HTTP/1.1 404 Not Found"
+              end
+
+              headers = [
+                "Content-Type: text/plain",
+                "Content-Length: #{body.bytesize}",
+                "Connection: close"
+              ].join("\r\n")
+
+              socket.write("#{status_line}\r\n#{headers}\r\n\r\n#{body}")
+            ensure
+              begin
+                socket.close
+              rescue StandardError
+              end
+            end
+          end
+        rescue => e
+          log_error("failed: #{e.class}: #{e.message}")
+        ensure
+          begin
+            @server&.close
+          rescue StandardError
+          end
+        end
+      end
+    end
+
+    def stop
+      return unless running?
+
+      begin
+        @server&.close
+      rescue StandardError
+      end
+
+      if @thread&.alive?
+        @thread.kill
+        @thread.join(1)
+      end
+
+      @server = nil
+      @thread = nil
+    end
+
+    def running?
+      @thread&.alive?
+    end
+
+    private
+
+      def default_logger
+        logger = Logger.new($stdout)
+        logger.level = Logger::INFO
+        logger.progname = "SolidQueueHTTP"
+        logger
+      end
+
+      def log_info(message)
+        @logger&.info(message)
+      end
+
+      def log_error(message)
+        @logger&.error(message)
+      end
+  end
+end

test/unit/health_server_test.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "net/http"
+require "socket"
+require "stringio"
+
+class HealthServerTest < ActiveSupport::TestCase
+  def setup
+    @host = "127.0.0.1"
+    @port = available_port(@host)
+    @server = SolidQueue::HealthServer.new(host: @host, port: @port, logger: Logger.new(IO::NULL))
+    @server.start
+    wait_for_server
+  end
+
+  def teardown
+    @server.stop if defined?(@server)
+  end
+
+  def test_health_endpoint_returns_ok
+    response = http_get("/health")
+    assert_equal "200", response.code
+    assert_equal "OK", response.body
+  end
+
+  def test_root_endpoint_returns_ok
+    response = http_get("/")
+    assert_equal "200", response.code
+    assert_equal "OK", response.body
+  end
+
+  def test_unknown_path_returns_not_found
+    response = http_get("/unknown")
+    assert_equal "404", response.code
+    assert_equal "Not Found", response.body
+  end
+
+  def test_stop_stops_server
+    assert @server.running?, "server should be running before stop"
+    @server.stop
+    assert_not @server.running?, "server should not be running after stop"
+  ensure
+    # Avoid double-stop in teardown if we stopped here
+    @server = SolidQueue::HealthServer.new(host: @host, port: @port, logger: Logger.new(IO::NULL))
+  end
+
+  def test_engine_skips_starting_health_server_when_puma_plugin_is_active
+    SolidQueue.health_server_enabled = true
+    SolidQueue.puma_plugin = true
+
+    server = SolidQueue.start_health_server
+    assert_nil server
+  ensure
+    SolidQueue.health_server_enabled = false
+    SolidQueue.puma_plugin = false
+  end
+
+  def test_logs_warning_when_skipped_under_puma_plugin
+    SolidQueue.health_server_enabled = true
+    SolidQueue.puma_plugin = true
+
+    original_logger = SolidQueue.logger
+    io = StringIO.new
+    SolidQueue.logger = Logger.new(io)
+
+    server = SolidQueue.start_health_server
+    assert_nil server
+
+    io.rewind
+    output = io.read
+    assert_includes output, "SolidQueue health server is enabled but Puma plugin is active; skipping starting health server to avoid duplicate servers"
+  ensure
+    SolidQueue.logger = original_logger if defined?(original_logger)
+    SolidQueue.health_server_enabled = false
+    SolidQueue.puma_plugin = false
+  end
+
+  private
+    def http_get(path)
+      Net::HTTP.start(@host, @port) do |http|
+        http.get(path)
+      end
+    end
+
+    def wait_for_server
+      # Try to connect for up to 1 second
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 1.0
+      begin
+        Net::HTTP.start(@host, @port) { |http| http.head("/") }
+      rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
+        raise if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+        sleep 0.05
+        retry
+      end
+    end
+
+    def available_port(host)
+      tcp = TCPServer.new(host, 0)
+      port = tcp.addr[1]
+      tcp.close
+      port
+    end
+end