gritz-core 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d69bbe23da7b5ec3c973bdbe3a2c2c1d1596b6632695f446ae6fb242d0d1f94
-  data.tar.gz: 89929d525c1709e164057aa7d684317db596734395371cf942019832cf7189bd
+  metadata.gz: 023ead58f761660de79d7168434d85be2f92e583073fab043b18b18fd14035c5
+  data.tar.gz: f319a9c5f6a190fad09e78667072ee22a5994dfe1f5c2e4f12287f3213865e1a
 SHA512:
-  metadata.gz: c4c61c0a88eedb466c3f556f9cd9861468f496b0ba6303be58133d58c6761d8d6fa6a1a9c4b51e7dd6bec168b8207aa8b82562d096f0ead5f8745e351a67c790
-  data.tar.gz: 5e7d9a717648f45c0f3774f3de35511608d6b6fa7fc5fc6f6be61fbf4d7b874c1cfafdd348b9441e0f37a528a30d341f3eddfa45aa50760255a42f7b644a58cf
+  metadata.gz: d531f928a935dd66d9a3459919fff84263309e6821da90332a841170b1bc268e2ccc711394a5873590611883136d44987d0d059794520d1335d788ad37815660
+  data.tar.gz: '08b50b33dcbb22fdde34c4052f2c15e82cfb1562bc83f450966f98879e4f0d8bc64cf50f8bb3517fae12ebfe4ac4841928f5ab5f5032a96eabd006711f8e44dc'

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.0
+
+- Supervise forked workers with boot and heartbeat timeouts, automatic replacement, graceful shutdown, lifecycle hooks, dynamic worker counts and log reopening.
+- Detect unsafe master-side gRPC initialization with ForkGuard and `gritz check`.
+- Add `Gritz::Testing::Cluster` for process lifecycle integration tests.
+
 ## 0.1.0
 
 Initial release.

data/README.md

@@ -1,6 +1,6 @@
 # Gritz Core
 
-Transport-independent controllers, routing, middleware, configuration and network-free testing for Ruby gRPC applications. Requires CRuby 3.3 or later. This gem has no grpc dependency and never loads a transport by itself.
+Transport-independent controllers, routing, middleware, configuration, forked-worker supervision and network-free testing for Ruby gRPC applications. Requires CRuby 3.3 or later. This gem has no grpc dependency. Requiring the core does not load a transport; starting a server loads the selected adapter.
 
 ```ruby
 require "gritz/core"

data/lib/gritz/cli.rb

@@ -4,13 +4,14 @@ require "optparse"
 require "logger"
 
 module Gritz
-  # Command line entry point for the single-process server and route listing.
+  # Starts a server, lists routes, or checks configuration and fork safety.
   # @api public
   class CLI
-    def initialize(stdout: $stdout, stderr: $stderr, env: ENV)
+    def initialize(stdout: $stdout, stderr: $stderr, env: ENV, status_io: nil)
       @stdout = stdout
       @stderr = stderr
       @env = env
+      @status_io = status_io
     end
 
     def run(argv)
@@ -18,7 +19,7 @@ module Gritz
       path = nil
       overrides = {}
       parser = OptionParser.new do |options|
-        options.banner = "Usage: gritz [start|routes] [-C config/gritz.rb] [options]"
+        options.banner = "Usage: gritz [start|routes|check] [-C config/gritz.rb] [options]"
         options.on("-C", "--config PATH", "Configuration file") { |value| path = value }
         options.on("--workers N", Integer) { |value| overrides[:workers] = value }
         options.on("--threads N", Integer) { |value| overrides[:threads] = value }
@@ -35,52 +36,51 @@ module Gritz
       end
       parser.parse!(args)
       command = args.shift || "start"
-      raise ConfigurationError, "Unknown command #{command}" unless %w[start routes].include?(command)
+      raise ConfigurationError, "Unknown command #{command}" unless %w[start routes check].include?(command)
       raise ConfigurationError, "Unexpected argument #{args.first}" unless args.empty?
 
       path ||= "config/gritz.rb" if File.file?("config/gritz.rb")
+      guard = ForkGuard.activate(mode: :record) if command != "routes"
+      require "gritz/native" if command != "routes"
       config = Configuration.load(path: path, env: @env, overrides: overrides)
-      config.validate_single_process! if command == "start"
-      config.preload! if config.preload_app?
       logger = Logger.new(@stdout)
       logger.formatter = ->(_severity, _time, _progname, message) { "#{message}\n" }
-      router = Router.new(controllers: config.controllers, strict: config.strict_routes, logger: logger)
+      if command == "check"
+        config.preload! if config.preload_app?
+        guard.violations.each { |violation| @stderr.puts(violation.message) }
+        return 1 unless guard.violations.empty?
+
+        config.validate_runtime!
+        Router.new(controllers: config.controllers, strict: config.strict_routes, logger: logger)
+        @stdout.puts "Configuration and fork safety checks passed"
+      elsif command == "start"
+        config.validate_runtime!
+        if config.workers.positive? && config.fork_mode == :clean
+          raise guard.violations.first if config.fork_guard == :raise && !guard.violations.empty?
+
+          guard.violations.each { |violation| logger.warn(violation.message) } if config.fork_guard == :warn
+        end
+        @stdout.sync = true if @stdout.respond_to?(:sync=)
+        return Supervisor::Master.new(config, logger: logger, status_io: @status_io).run if config.workers.positive?
+
+        ForkGuard.deactivate
+        config.preload! if config.preload_app?
+        return Worker::Runner.new(index: 0, config: config, logger: logger).run
+      else
+        config.preload! if config.preload_app?
+        router = Router.new(controllers: config.controllers, strict: config.strict_routes, logger: logger)
+      end
       if command == "routes"
         router.routes.each_value do |route|
           @stdout.puts "#{route.full_name} #{route.kind} #{route.controller}##{route.action}"
         end
-      else
-        start(config, router, logger)
       end
       0
-    rescue ConfigurationError, OptionParser::ParseError, ArgumentError, Errno::ENOENT, SyntaxError, LoadError => e
+    rescue ConfigurationError, ForkGuard::Violation, ArgumentError, Errno::ENOENT, SyntaxError, LoadError, RuntimeError => e
       @stderr.puts "gritz: #{e.message}"
       1
-    end
-
-    private
-
-    def start(config, router, logger)
-      @stdout.sync = true if @stdout.respond_to?(:sync=)
-      # Load the adapter only when starting; route inspection stays transport-independent.
-      require "gritz/native"
-      dispatcher = Dispatcher.new(router: router, middleware: config.middleware, logger: logger)
-      adapter = Transport::Native.new(config: config, dispatcher: dispatcher, logger: logger)
-      signals = []
-      previous = %w[TERM INT QUIT].to_h { |name| [name, Signal.trap(name) { signals << name }] }
-      config.run_hooks(:on_worker_boot, 0)
-      port = adapter.bind(config.bind)
-      adapter.start
-      logger.info("Gritz #{Core::VERSION} listening on #{config.bind.sub(/:\d+\z/, ":#{port}")}")
-      while signals.empty?
-        sleep 0.05
-        raise ConfigurationError, "gRPC server stopped unexpectedly" unless adapter.running?
-      end
-      signals.shift == "QUIT" ? adapter.kill : adapter.stop(deadline: Time.now + config.shutdown_timeout)
     ensure
-      previous&.each { |name, handler| Signal.trap(name, handler) }
-      adapter&.kill if adapter&.running?
-      config.run_hooks(:on_worker_shutdown, 0)
+      ForkGuard.deactivate if guard
     end
   end
 end

data/lib/gritz/configuration.rb

@@ -3,7 +3,7 @@
 require "json"
 
 module Gritz
-  # Startup settings. Process-related settings are reserved for the supervisor.
+  # Validated startup settings for single-process and supervised servers.
   # @api public
   class Configuration
     DEFAULTS = {
@@ -46,6 +46,7 @@ module Gritz
       DSL.new(config).evaluate(path) if path
       env.each do |key, value|
         next unless key.start_with?("GRITZ_")
+        next if key == "GRITZ_RELEASE" # Dependency selection in the release workflow, not a runtime setting.
 
         name = key.delete_prefix("GRITZ_").downcase.to_sym
         raise ConfigurationError, "Unknown environment setting #{key}" unless DEFAULTS.key?(name)
@@ -104,22 +105,28 @@ module Gritz
     def preload_app? = preload_app
 
     # Fail before allocating transport resources for unsupported release features.
-    def validate_single_process!
+    def validate_runtime!
       validate!
-      raise ConfigurationError, "v0.1 supports workers 0; the supervisor is planned for v0.2" unless workers.zero?
-      raise ConfigurationError, "v0.1 supports transport :native" unless transport == :native
-      raise ConfigurationError, "v0.1 supports listener_strategy :reuseport" unless listener_strategy == :reuseport
+      raise ConfigurationError, "This release supports transport :native" unless transport == :native
+      raise ConfigurationError, "This release supports listener_strategy :reuseport" unless listener_strategy == :reuseport
       raise ConfigurationError, "TLS is planned for v0.3" unless tls.empty?
-      raise ConfigurationError, "worker_recycle requires the supervisor" unless worker_recycle.empty?
+      raise ConfigurationError, "worker_recycle is planned for v0.3" unless worker_recycle.empty?
       raise ConfigurationError, "Health checks are planned for v0.3" unless health_checks.empty?
-      raise ConfigurationError, "v0.1 supports log_format :json" unless log_format == :json
-      raise ConfigurationError, "v0.1 reserves metrics_backend :pipe; metrics export is planned for v0.3" unless metrics_backend == :pipe
-      raise ConfigurationError, "grpc_fork_support requires the supervisor" unless fork_mode == :clean
+      raise ConfigurationError, "This release supports log_format :json" unless log_format == :json
+      raise ConfigurationError, "This release reserves metrics_backend :pipe; metrics export is planned for v0.3" unless metrics_backend == :pipe
+      raise ConfigurationError, "grpc_fork_support requires workers > 0" if workers.zero? && fork_mode != :clean
       raise ConfigurationError, "at least one controller must be registered" if controllers.empty?
 
       self
     end
 
+    def validate_single_process!
+      validate_runtime!
+      raise ConfigurationError, "Testing::Server requires workers 0; use Testing::Cluster for supervised servers" unless workers.zero?
+
+      self
+    end
+
     def add_preloader(&block)
       @preload_app = true
       @preloaders << block if block

data/lib/gritz/core/version.rb

@@ -2,6 +2,6 @@
 
 module Gritz
   module Core
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/gritz/fork_guard.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Gritz
+  # Detects transport resource constructors in the master before workers fork.
+  # @api public
+  class ForkGuard
+    class Violation < StandardError
+      attr_reader :klass, :locations
+
+      def initialize(klass, locations)
+        @klass = klass
+        @locations = locations
+        super("gRPC object was created in the master process before fork.\n  " \
+              "#{klass}.new\n#{locations.map { |location| "    from #{location}" }.join("\n")}\n" \
+              "Fix: create it in an on_worker_boot hook.")
+      end
+    end
+
+    module ConstructorHook
+      def new(...)
+        Gritz::ForkGuard.check!(self)
+        super
+      end
+    end
+
+    attr_reader :mode, :logger, :master_pid, :violations
+
+    class << self
+      attr_reader :current
+
+      def activate(mode: :raise, logger: nil, master_pid: Process.pid)
+        @current = new(mode:, logger:, master_pid:)
+      end
+
+      def deactivate
+        @current = nil
+      end
+
+      def install(klass)
+        klass.singleton_class.prepend(ConstructorHook) unless klass.singleton_class.ancestors.include?(ConstructorHook)
+      end
+
+      def master?
+        @current&.master? || false
+      end
+
+      def check!(klass)
+        guard = @current
+        return unless guard && guard.mode != :off && guard.master?
+
+        locations = caller_locations(1, 8).reject { |location| location.path == __FILE__ }
+        violation = Violation.new(klass, locations)
+        guard.violations << violation
+        case guard.mode
+        when :raise then raise violation
+        when :warn
+          guard.logger ? guard.logger.warn(violation.message) : Kernel.warn(violation.message)
+        end
+      end
+    end
+
+    def initialize(mode:, logger:, master_pid:)
+      raise ArgumentError, "fork guard mode must be :raise, :warn, :off, or :record" unless %i[raise warn off record].include?(mode)
+
+      @mode = mode
+      @logger = logger
+      @master_pid = master_pid
+      @violations = []
+    end
+
+    def master?
+      Process.pid == @master_pid
+    end
+  end
+end

data/lib/gritz/supervisor/master.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Gritz
+  module Supervisor
+    # Forks workers, monitors their status pipes, and owns every child until reaped.
+    # @api public
+    class Master
+      SIGNALS = %w[TERM INT QUIT TTIN TTOU HUP CHLD].freeze
+      attr_reader :workers
+
+      def initialize(config, logger: Logger.new($stdout), status_io: nil)
+        @config = config
+        @logger = logger
+        @workers = {}
+        @desired = config.workers
+        @reports = StatusChannel.new(status_io) if status_io
+        @exit_status = 0
+      end
+
+      def run
+        @config.validate_runtime!
+        raise ConfigurationError, "Supervisor requires workers > 0" unless @desired.positive?
+
+        require "gritz/native"
+        @signals = SignalQueue.new(signals: SIGNALS)
+        @guard = ForkGuard.activate(mode: @config.fork_mode == :clean ? @config.fork_guard : :off, logger: @logger)
+        @config.preload! if @config.preload_app?
+        Process.warmup if @config.preload_app? && Process.respond_to?(:warmup)
+        if @config.workers > 1 && !RUBY_PLATFORM.include?("linux")
+          @logger.warn("Multiple native workers require Linux for SO_REUSEPORT load balancing; use workers 0 on macOS")
+        end
+        maintain_worker_count
+        loop do
+          @signals.drain.each { |signal| handle_signal(signal) }
+          read_statuses
+          reap_children
+          check_timeouts
+          maintain_worker_count unless @shutdown_at
+          @reports&.write(status)
+          break if @shutdown_at && @workers.empty?
+
+          IO.select([@signals.io, *@workers.values.filter_map { |handle| handle.channel.io unless handle.channel.closed? }], nil, nil, 0.05)
+        end
+        @exit_status
+      ensure
+        cleanup
+        ForkGuard.deactivate if @guard
+      end
+
+      def status
+        { pid: Process.pid, state: @shutdown_at ? "draining" : "running", workers: @workers.values.map(&:to_h) }
+      end
+
+      private
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def maintain_worker_count
+        used = @workers.values.map(&:index)
+        (@desired - @workers.size).times do
+          index = (0...@desired).find { |candidate| !used.include?(candidate) }
+          spawn_worker(index)
+          used << index
+        end
+      end
+
+      def spawn_worker(index)
+        reader, writer = IO.pipe
+        @config.run_hooks(:before_fork, index)
+        experimental = @config.fork_mode == :grpc_fork_support
+        if experimental
+          require "gritz/native"
+          Transport::Native.prefork
+          prepared = true
+        end
+        pid = Process.fork do
+          exit_status = 1
+          begin
+            reader.close
+            # Restore all inherited master traps, including CHLD and resize signals.
+            @signals.close
+            @reports&.close
+            @workers.each_value(&:close)
+            Transport::Native.postfork_child if experimental
+            exit_status = Worker::Runner.new(index: index, status_io: writer, config: @config, logger: @logger).run
+          rescue StandardError, LoadError, SyntaxError, SystemExit => e
+            @logger.error("Worker #{index} failed: #{e.full_message}")
+            exit_status = 1
+          ensure
+            begin
+              writer.close unless writer.closed?
+            ensure
+              # Never unwind the inherited master ensure or run application at_exit hooks.
+              Process.exit!(exit_status)
+            end
+          end
+        end
+        writer.close
+        @workers[pid] = WorkerHandle.new(pid: pid, index: index, status_io: reader)
+        @logger.info("Worker #{index} spawned pid=#{pid}")
+      rescue StandardError
+        reader&.close unless reader&.closed?
+        writer&.close unless writer&.closed?
+        raise
+      ensure
+        Transport::Native.postfork_parent if prepared
+      end
+
+      def read_statuses
+        @workers.each_value do |handle|
+          handle.channel.read.each do |message|
+            handle.update(message, now: now)
+            if message[:state] == "failed" && !@ever_ready
+              @exit_status = 1
+              begin_shutdown(immediate: true)
+            end
+            @ever_ready = true if message[:state] == "ready"
+          rescue ConfigurationError => e
+            @logger.error("Worker #{handle.pid}: #{e.message}")
+            kill(handle)
+          end
+        end
+      end
+
+      def reap_children
+        # Only reap owned children: application hooks can start unrelated subprocesses.
+        @workers.each_key do |pid|
+          result = Process.waitpid2(pid, Process::WNOHANG)
+          next unless result
+
+          handle = @workers.delete(pid)
+          handle.close
+          child_status = result.last
+          @logger.info("Worker #{handle.index} exited pid=#{pid} status=#{child_status}")
+          startup_failed = child_status.exited? && !@ever_ready && !@shutdown_at && !handle.term_at
+          shutdown_failed = @shutdown_at && child_status.exited? && !child_status.success?
+          if handle.state != "killed" && (startup_failed || shutdown_failed)
+            @exit_status = 1
+            begin_shutdown(immediate: true) if startup_failed
+          end
+        rescue Errno::ECHILD
+          @workers.delete(pid)&.close
+        end
+      end
+
+      def handle_signal(signal)
+        case signal
+        when "TERM", "INT" then begin_shutdown
+        when "QUIT" then begin_shutdown(immediate: true)
+        when "TTIN"
+          if !@shutdown_at && @config.bind.end_with?(":0")
+            @logger.warn("Cannot add a reuseport worker with port 0; configure a fixed bind port")
+          elsif !@shutdown_at
+            @desired += 1
+          end
+        when "TTOU"
+          if !@shutdown_at && @desired > 1
+            @desired -= 1
+            retire(@workers.values.reject(&:term_at).max_by(&:index))
+          end
+        when "HUP"
+          @logger.reopen
+          @workers.each_key { |pid| send_signal("HUP", pid) }
+          @logger.info("Log reopened")
+        end
+      end
+
+      def begin_shutdown(immediate: false)
+        @shutdown_at ||= now
+        if immediate
+          @workers.each_value { |handle| kill(handle) }
+        else
+          @workers.each_value { |handle| handle.term_at ||= @shutdown_at + @config.drain_delay }
+        end
+      end
+
+      def retire(handle)
+        return unless handle
+
+        handle.term_at = now
+        handle.state = "draining"
+      end
+
+      def check_timeouts
+        timestamp = now
+        @workers.each_value do |handle|
+          next if handle.state == "killed"
+
+          if handle.term_at && timestamp >= handle.term_at && !handle.kill_at
+            handle.state = "draining"
+            send_signal("TERM", handle.pid)
+            handle.kill_at = timestamp + @config.shutdown_timeout
+          end
+          if handle.kill_at
+            kill(handle) if timestamp >= handle.kill_at
+          elsif !@shutdown_at
+            elapsed = timestamp - (handle.state == "booting" ? handle.born_at : handle.last_seen)
+            timeout = handle.state == "booting" ? @config.worker_boot_timeout : @config.worker_timeout
+            if elapsed > timeout
+              @logger.error("Worker #{handle.pid} #{handle.state} timeout after #{elapsed.round(2)}s")
+              kill(handle)
+            end
+          end
+        end
+      end
+
+      def kill(handle)
+        handle.state = "killed"
+        send_signal("KILL", handle.pid)
+      end
+
+      def send_signal(signal, pid)
+        Process.kill(signal, pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def cleanup
+        @workers.each_value { |handle| kill(handle) }
+        @workers.each_value do |handle| # rubocop:disable Style/CombinableLoops -- kill every child before waiting for any child
+          Process.waitpid(handle.pid)
+        rescue Errno::ECHILD
+          nil
+        ensure
+          handle.close
+        end
+        @workers.clear
+        @signals&.close
+        @reports&.close
+      end
+    end
+  end
+end

data/lib/gritz/supervisor/signal_queue.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Supervisor
+    # Wakes the event loop without doing process or logger work in a signal trap.
+    # @api private
+    class SignalQueue
+      attr_reader :io
+
+      def initialize(signals:)
+        @io, @writer = IO.pipe
+        @pending = []
+        @previous = {}
+        signals.each do |name|
+          @previous[name] = Signal.trap(name) do
+            @pending << name unless @pending.include?(name)
+            @writer.write_nonblock(".", exception: false)
+          rescue IOError, Errno::EPIPE
+            nil
+          end
+        end
+      rescue StandardError
+        close
+        raise
+      end
+
+      def drain
+        loop do
+          break unless @io.read_nonblock(4096, exception: false).is_a?(String)
+        end
+        # Swap instead of clearing: a signal arriving here belongs to the next drain.
+        pending = @pending
+        @pending = []
+        pending
+      end
+
+      def close
+        @previous&.each { |name, handler| Signal.trap(name, handler) }
+        @previous = {}
+        close_in_child
+      end
+
+      def close_in_child
+        @io&.close unless @io&.closed?
+        @writer&.close unless @writer&.closed?
+      end
+    end
+  end
+end

data/lib/gritz/supervisor/status_channel.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Gritz
+  module Supervisor
+    # Bounded, nonblocking JSON Lines over a worker's dedicated status pipe.
+    # @api private
+    class StatusChannel
+      # ponytail: master snapshots are capped at 64 KiB; chunk reports if clusters outgrow this bound.
+      MAX_LINE_BYTES = 64 * 1024
+      MAX_READ_BYTES = 64 * 1024
+
+      attr_reader :io
+
+      def initialize(io)
+        @io = io
+        @buffer = +""
+        @pending = +""
+        @discarding = false
+        @closed = io.closed?
+      end
+
+      def write(status)
+        return false if closed? || flush_pending.positive?
+
+        line = "#{JSON.generate(status)}\n"
+        return false if line.bytesize > MAX_LINE_BYTES
+
+        @pending = line
+        flush_pending.zero?
+      rescue JSON::GeneratorError, JSON::NestingError
+        false
+      rescue IOError, SystemCallError
+        close
+        false
+      end
+
+      def read
+        rows = []
+        return rows if closed?
+
+        remaining = MAX_READ_BYTES
+        while remaining.positive?
+          chunk = @io.read_nonblock([4096, remaining].min, exception: false)
+          break if chunk == :wait_readable
+
+          if chunk.nil?
+            close
+            break
+          end
+
+          remaining -= chunk.bytesize
+          consume(chunk, rows)
+        end
+        rows
+      rescue IOError, SystemCallError
+        close
+        rows
+      end
+
+      def closed? = @closed || @io.closed?
+
+      def close
+        @closed = true
+        @buffer.clear
+        @pending.clear
+        @io.close unless @io.closed?
+        nil
+      rescue IOError
+        nil
+      end
+
+      private
+
+      def flush_pending
+        return 0 if @pending.empty?
+
+        written = @io.write_nonblock(@pending, exception: false)
+        return @pending.bytesize if written == :wait_writable
+
+        @pending = @pending.byteslice(written..) || +""
+        @pending.bytesize
+      end
+
+      def consume(chunk, rows)
+        chunk.each_line do |part|
+          complete = part.end_with?("\n")
+          unless @discarding
+            @buffer << part
+            if @buffer.bytesize > MAX_LINE_BYTES
+              @buffer.clear
+              @discarding = true
+            end
+          end
+          next unless complete
+
+          unless @discarding
+            begin
+              row = JSON.parse(@buffer, symbolize_names: true)
+              rows << row if row.is_a?(Hash)
+            rescue JSON::ParserError
+              # A damaged record does not prevent subsequent status updates.
+            end
+          end
+          @buffer.clear
+          @discarding = false
+        end
+      end
+    end
+  end
+end

data/lib/gritz/supervisor/worker_handle.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Supervisor
+    # Parent-owned worker state; heartbeat deadlines use the parent's monotonic clock.
+    # @api private
+    class WorkerHandle
+      STATES = %w[booting ready draining failed stopped killed].freeze
+      attr_reader :pid, :index, :channel, :born_at, :last_seen, :stats
+      attr_accessor :state, :term_at, :kill_at
+
+      def initialize(pid:, index:, status_io:, now: Process.clock_gettime(Process::CLOCK_MONOTONIC))
+        @pid = pid
+        @index = index
+        @channel = StatusChannel.new(status_io)
+        @born_at = @last_seen = now
+        @state = "booting"
+        @stats = {}
+      end
+
+      def update(message, now:)
+        raise ConfigurationError, "Invalid worker state #{message[:state].inspect}" unless STATES.include?(message[:state])
+
+        @last_seen = now
+        @stats = message.except(:pid, :index, :state)
+        # A late heartbeat must not undo the parent's decision to retire this worker.
+        @state = message[:state] unless %w[draining killed].include?(@state)
+      end
+
+      def to_h = @stats.merge(pid: @pid, index: @index, state: @state)
+      def close = @channel.close
+    end
+  end
+end

data/lib/gritz/testing/cluster.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "tempfile"
+require "timeout"
+require "io/wait"
+
+module Gritz
+  module Testing
+    # Starts a supervisor in a fresh interpreter, avoiding gRPC state inherited from a test process.
+    # @api public
+    class Cluster
+      MAX_LOG_BYTES = 64 * 1024
+
+      attr_reader :pid
+
+      def self.start(**)
+        cluster = new(**).start
+        return cluster unless block_given?
+
+        begin
+          yield cluster
+        ensure
+          cluster.stop
+        end
+      end
+
+      def initialize(config_path:, env: {}, command: nil)
+        @config_path = File.expand_path(config_path)
+        @env = env
+        @command = command
+        @status = { state: "starting", workers: [] }
+      end
+
+      def start
+        raise ArgumentError, "cluster is already started" if @pid
+
+        @reader, writer = IO.pipe
+        @channel = Supervisor::StatusChannel.new(@reader)
+        @log = Tempfile.new(["gritz-cluster", ".log"])
+        command = @command || [
+          RbConfig.ruby, "-I", $LOAD_PATH.join(File::PATH_SEPARATOR), "-rgritz/core", "-e",
+          "exit Gritz::CLI.new(status_io: IO.for_fd(3)).run(ARGV)", "--", "start", "-C", @config_path
+        ]
+        @pid = Process.spawn(@env, *command, 3 => writer, out: @log, err: @log, pgroup: true)
+        self
+      rescue StandardError
+        unless @pid
+          @channel&.close
+          @log&.close!
+        end
+        raise
+      ensure
+        writer&.close
+      end
+
+      def status
+        @channel&.read&.each { |row| @status = row }
+        @status
+      end
+
+      def workers = status.fetch(:workers, [])
+
+      def logs
+        return @logs || "" unless @log && !@log.closed?
+
+        @log.flush
+        File.open(@log.path) do |file|
+          file.seek([file.size - MAX_LOG_BYTES, 0].max)
+          file.read
+        end
+      end
+
+      def signal(name, pid: @pid)
+        raise ArgumentError, "cluster is not started" unless pid
+
+        Process.kill(name, pid)
+        self
+      end
+
+      # A predicate can inspect snapshots without fixed sleeps or dependence on log wording.
+      def wait_until(state: "ready", workers: nil, timeout: 10)
+        deadline = monotonic + timeout
+        loop do
+          snapshot = status
+          ready = if state == "ready"
+                    snapshot[:state] == "running" && snapshot[:workers]&.any? && snapshot[:workers].all? { |worker| worker[:state] == "ready" }
+                  else
+                    state.nil? || snapshot[:state] == state
+                  end
+          count = workers.nil? || snapshot.fetch(:workers, []).size == workers
+          return self if ready && count && (!block_given? || yield(snapshot))
+
+          if exited?
+            raise "cluster exited #{@exit_status.inspect} before reaching #{state.inspect}\n#{logs}"
+          end
+          raise Timeout::Error, "cluster did not reach #{state.inspect}: #{snapshot.inspect}\n#{logs}" if monotonic >= deadline
+
+          pause = (deadline - monotonic).clamp(0, 0.05)
+          @reader.closed? ? sleep(pause) : @reader.wait_readable(pause)
+        end
+      end
+
+      def wait(timeout: 10)
+        raise ArgumentError, "cluster is not started" unless @pid
+
+        deadline = monotonic + timeout
+        until exited?
+          raise Timeout::Error, "cluster did not exit\n#{logs}" if monotonic >= deadline
+
+          sleep((deadline - monotonic).clamp(0, 0.01))
+        end
+        @exit_status
+      end
+
+      def stop(timeout: 10)
+        return self unless @pid
+
+        signal("TERM") unless exited?
+        wait(timeout:)
+        self
+      rescue Timeout::Error
+        begin
+          Process.kill("KILL", -@pid)
+        rescue Errno::ESRCH
+          # The process group may have exited between the timeout and kill.
+        end
+        wait(timeout: 5)
+        self
+      ensure
+        @channel&.close
+        @logs = logs
+        @log&.close!
+      end
+
+      private
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def exited?
+        return true if @exit_status
+        return false unless @pid
+
+        pair = Process.waitpid2(@pid, Process::WNOHANG)
+        @exit_status = pair&.last
+        !@exit_status.nil?
+      end
+    end
+  end
+end

data/lib/gritz/worker/runner.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "io/wait"
+
+module Gritz
+  module Worker
+    # Owns transport resources and heartbeats in one serving process.
+    # @api private
+    class Runner
+      def initialize(index:, config:, logger:, status_io: nil)
+        @index = index
+        @config = config
+        @logger = logger
+        @status = Supervisor::StatusChannel.new(status_io) if status_io
+      end
+
+      def run
+        @exit_status = 0
+        begin
+          @signals = Supervisor::SignalQueue.new(signals: %w[TERM INT QUIT HUP])
+          report("booting")
+          require "gritz/native"
+          @boot_started = true
+          @config.preload! unless @config.preload_app?
+          @config.run_hooks(:on_worker_boot, @index)
+          router = Router.new(controllers: @config.controllers, strict: @config.strict_routes, logger: @logger)
+          dispatcher = Dispatcher.new(router:, middleware: @config.middleware, logger: @logger)
+          @adapter = Transport::Native.new(config: @config, dispatcher:, logger: @logger)
+          @port = @adapter.bind(@config.bind)
+          @adapter.start
+          @logger.info("Gritz #{Core::VERSION} listening on #{@config.bind.sub(/:\d+\z/, ":#{@port}")}")
+          report("ready")
+          serve
+        rescue StandardError, LoadError, SyntaxError, SystemExit => e
+          fail_worker(e)
+        ensure
+          finish
+        end
+        @exit_status
+      end
+
+      private
+
+      def serve
+        next_status = monotonic + @config.status_interval
+        loop do
+          raise ConfigurationError, "gRPC server stopped unexpectedly" unless @adapter.running?
+          raise ConfigurationError, "worker status pipe closed" if @status&.closed?
+
+          @signals.drain.each do |name|
+            case name
+            when "HUP" then @logger.reopen
+            when "QUIT"
+              report("draining")
+              @adapter.kill
+              @transport_stopped = true
+              return 0
+            when "TERM", "INT"
+              report("draining")
+              @adapter.stop(deadline: Time.now + @config.shutdown_timeout)
+              @transport_stopped = true
+              return 0
+            end
+          end
+          now = monotonic
+          if now >= next_status
+            report("ready")
+            next_status = now + @config.status_interval
+          end
+          @signals.io.wait_readable([next_status - monotonic, 0].max)
+        end
+      end
+
+      def report(state, include_stats: true, **extra)
+        return unless @status
+
+        stats = include_stats && @adapter ? @adapter.stats : {}
+        row = { inflight: 0, capacity: @config.threads, requests_total: 0, oldest_inflight_age: 0 }.merge(stats)
+        row.merge!(pid: Process.pid, index: @index, state:, ts: monotonic, port: @port,
+                   busy_threads: stats.fetch(:busy_threads, stats.fetch(:busy, 0)))
+        @status.write(row.merge(extra))
+      end
+
+      def fail_worker(error)
+        @exit_status = 1
+        @logger.error(error.full_message)
+        report("failed", include_stats: false, error: error.message[0, 512])
+      end
+
+      def finish
+        cleanup { @adapter&.kill unless @transport_stopped }
+        cleanup { @config.run_hooks(:on_worker_shutdown, @index) if @boot_started }
+        report("stopped", include_stats: false, exit_status: @exit_status)
+      ensure
+        begin
+          @signals&.close
+        ensure
+          @status&.close
+        end
+      end
+
+      def cleanup
+        yield
+      rescue StandardError, LoadError, SyntaxError, SystemExit => e
+        fail_worker(e)
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gritz-core
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -111,6 +111,7 @@ files:
 - lib/gritz/dispatcher.rb
 - lib/gritz/dsl.rb
 - lib/gritz/errors.rb
+- lib/gritz/fork_guard.rb
 - lib/gritz/method_descriptor.rb
 - lib/gritz/middleware/context.rb
 - lib/gritz/middleware/exception_mapper.rb
@@ -118,10 +119,16 @@ files:
 - lib/gritz/middleware/request_id.rb
 - lib/gritz/middleware/stack.rb
 - lib/gritz/router.rb
+- lib/gritz/supervisor/master.rb
+- lib/gritz/supervisor/signal_queue.rb
+- lib/gritz/supervisor/status_channel.rb
+- lib/gritz/supervisor/worker_handle.rb
+- lib/gritz/testing/cluster.rb
 - lib/gritz/testing/in_memory_call.rb
 - lib/gritz/testing/minitest.rb
 - lib/gritz/testing/rpc_helper.rb
 - lib/gritz/testing/rspec.rb
+- lib/gritz/worker/runner.rb
 homepage: https://github.com/gritzrpc/gritz-core
 licenses:
 - MIT
@@ -144,7 +151,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Transport-independent controllers and middleware for Gritz
 test_files: []