ractor_shepherd 0.1.0

data/lib/ractor_shepherd/event_logger.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  # Reads an event port and writes each event to a logger.
+  #
+  #   events = Ractor::Port.new
+  #   RactorShepherd::EventLogger.start(events)                              # to stderr
+  #   RactorShepherd::EventLogger.start(events, logger: Logger.new($stdout)) #=> Thread
+  #
+  # Any object that answers `info`, `warn` and `error` will do. Ruby 4.0 no
+  # longer ships logger as a default gem, so this gem never requires it.
+  module EventLogger
+    # Something went wrong.
+    ERROR_TYPES = Ractor.make_shareable(%i[child_unresponsive max_restarts_exceeded])
+    # Something is being restarted.
+    WARN_TYPES = Ractor.make_shareable(%i[child_start_failed child_restart_scheduled])
+
+    # The default logger: one line per event on stderr.
+    class StderrLogger
+      def info(message) = write("INFO", message)
+      def warn(message) = write("WARN", message)
+      def error(message) = write("ERROR", message)
+
+      private
+
+      def write(level, message)
+        # Not Kernel#warn: it would collide with StderrLogger#warn.
+        $stderr.write("#{level} -- #{message}\n")
+      end
+    end
+
+    module_function
+
+    # Start a thread, in the calling Ractor, that drains the port.
+    #
+    # The port must have been created by the calling Ractor, since only its
+    # creator may receive from it.
+    #
+    # @return [Thread]
+    def start(port, logger: StderrLogger.new)
+      Thread.new(port, logger) do |pt, log|
+        while true # `loop do` is forbidden here: Ractor::ClosedError < StopIteration
+          event = pt.receive
+          log.public_send(EventLogger.level_for(event), EventLogger.format_event(event))
+        end
+      rescue Ractor::ClosedError
+        # The port closed. Stop reading.
+        nil
+      end
+    end
+
+    # @return [Symbol] :info, :warn or :error
+    def level_for(event)
+      type = event[:type]
+      return :error if ERROR_TYPES.include?(type)
+      return :error if type == :child_exited && event[:reason] == :error
+      return :warn if WARN_TYPES.include?(type)
+      return :warn if type == :child_started && event[:attempt].to_i.positive?
+
+      :info
+    end
+
+    # @return [String] one line
+    def format_event(event)
+      head = "[ractor_shepherd] #{event[:supervisor]} #{event[:type]}"
+      rest = event.except(:type, :supervisor, :at).map { |key, value| "#{key}=#{value.inspect}" }
+      [head, *rest].join(" ")
+    end
+  end
+end

data/lib/ractor_shepherd/facade.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# The public entry points.
+module RactorShepherd
+  class << self
+    # Start a root supervisor.
+    #
+    # Starting is synchronous: this returns once every child's `initialize` has
+    # finished. If one of them fails, the children that already started are
+    # stopped in reverse order and {StartError} is raised.
+    #
+    # @return [SupervisorRef]
+    def start(name:, strategy: :one_for_one, children: [], max_restarts: 3, max_seconds: 5.0,
+              on_unresponsive: :escalate, event_port: nil, boot_timeout: 30)
+      spec = Validator.root_spec(kind: :static, strategy: strategy, children: children,
+                                 max_restarts: max_restarts, max_seconds: max_seconds,
+                                 on_unresponsive: on_unresponsive)
+      Runtime::SupervisorServer.boot(spec, name: name, event_port: event_port, boot_timeout: boot_timeout)
+    end
+
+    # Start a root dynamic supervisor, which begins with no children.
+    #
+    # @return [SupervisorRef]
+    def start_dynamic(name:, max_children: nil, max_restarts: 3, max_seconds: 5.0,
+                      on_unresponsive: :escalate, event_port: nil, boot_timeout: 30)
+      spec = Validator.root_spec(kind: :dynamic, strategy: :one_for_one, children: [],
+                                 max_restarts: max_restarts, max_seconds: max_seconds,
+                                 max_children: max_children, on_unresponsive: on_unresponsive)
+      Runtime::SupervisorServer.boot(spec, name: name, event_port: event_port, boot_timeout: boot_timeout)
+    end
+
+    # Start a supervisor, yield it, and stop it on the way out.
+    def run(**)
+      supervisor = start(**)
+      begin
+        yield supervisor
+      ensure
+        supervisor.stop
+      end
+    end
+
+    # Describe a worker child.
+    #
+    # @param id [Symbol, Integer, String] unique within its supervisor
+    # @param klass [Class] a class that includes RactorShepherd::Worker
+    def worker(id, klass, args: [], kwargs: {}, restart: :permanent,
+               shutdown_timeout: 5.0, start_timeout: 5.0, restart_delay: nil)
+      Validator.worker_spec(id, klass, args: args, kwargs: kwargs, restart: restart,
+                                       shutdown_timeout: shutdown_timeout, start_timeout: start_timeout,
+                                       restart_delay: restart_delay, allow_nil_id: id.nil?)
+    end
+
+    # Describe a supervisor child.
+    def supervisor(id, strategy: :one_for_one, children: [], max_restarts: 3, max_seconds: 5.0,
+                   on_unresponsive: :escalate, restart: :permanent,
+                   shutdown_timeout: :infinity, start_timeout: :infinity, restart_delay: nil)
+      Validator.supervisor_spec(id, kind: :static, strategy: strategy, children: children,
+                                    max_restarts: max_restarts, max_seconds: max_seconds,
+                                    on_unresponsive: on_unresponsive, restart: restart,
+                                    shutdown_timeout: shutdown_timeout, start_timeout: start_timeout,
+                                    restart_delay: restart_delay)
+    end
+
+    # Describe a dynamic supervisor child.
+    def dynamic_supervisor(id, max_children: nil, max_restarts: 3, max_seconds: 5.0,
+                           on_unresponsive: :escalate, restart: :permanent,
+                           shutdown_timeout: :infinity, start_timeout: :infinity, restart_delay: nil)
+      Validator.supervisor_spec(id, kind: :dynamic, strategy: :one_for_one, children: [],
+                                    max_restarts: max_restarts, max_seconds: max_seconds,
+                                    max_children: max_children, on_unresponsive: on_unresponsive,
+                                    restart: restart, shutdown_timeout: shutdown_timeout,
+                                    start_timeout: start_timeout, restart_delay: restart_delay)
+    end
+  end
+end

data/lib/ractor_shepherd/runtime/call.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  module Runtime
+    # A synchronous request/response over a one-shot reply port.
+    #
+    # Ruby 4.0's `Ractor#unmonitor` looks registrations up by port id alone and
+    # ignores which Ractor created the port. Since port ids are a per Ractor
+    # sequence, unmonitoring can silently drop *another* Ractor's monitor of the
+    # same target, which would leave a supervisor blind to its own child dying.
+    # So this gem never calls `unmonitor`. See DESIGN.md F24 and the reproduction
+    # in spike/unmonitor_id_collision.rb.
+    #
+    # Registrations we cannot remove would pile up if every call added one, so a
+    # call with a finite timeout does not monitor at all: a dead target is found
+    # out either when the send raises ClosedError, or after the timeout by
+    # checking whether the target is still alive.
+    #
+    # ponytail: one port and one timer thread per call. Hot paths should use
+    # `cast` or their own port instead; the README says so.
+    #
+    # @api private
+    module Call
+      module_function
+
+      # @param target_ractor [Ractor] the Ractor being called
+      # @param target_port [Ractor::Port, Ractor] where the request goes
+      # @param timeout [Numeric, :infinity]
+      # @param down_error [Class] raised when the target is not running
+      # @return [Object] the reply payload
+      def perform(target_ractor, target_port, request, timeout: 5, down_error: SupervisorDown)
+        reply = Ractor::Port.new
+        timer = nil
+        if timeout == :infinity
+          # Only an unbounded call needs a monitor, so that it cannot wait forever.
+          # monitor returns false when the target has already finished.
+          raise down_error, down_message(target_ractor, "is not running") unless target_ractor.monitor(reply)
+        else
+          timer = Timer.for_current_ractor.after(timeout, reply, Protocol.timeout(0))
+        end
+
+        begin
+          target_port << Protocol.call(reply, request)
+        rescue Ractor::ClosedError
+          # Sending to something that has already finished raises ClosedError.
+          raise down_error, down_message(target_ractor, "is not running")
+        end
+
+        await(reply, target_ractor, down_error)
+      ensure
+        timer&.cancel
+        reply&.close
+      end
+
+      def await(reply, target_ractor, down_error)
+        case (msg = reply.receive)
+        in [Protocol::REPLY, result] then result
+        in [Protocol::TIMEOUT, _]
+          raise down_error, down_message(target_ractor, "terminated while handling the call") if
+            terminated?(target_ractor)
+
+          raise CallTimeout, down_message(target_ractor, "did not reply within the timeout")
+        else
+          # A monitor notification; Compat validates its shape. The target went down.
+          Compat.monitor_status(msg)
+          raise down_error, down_message(target_ractor, "terminated while handling the call")
+        end
+      end
+
+      # Has the target finished?
+      #
+      # When it is still alive this leaves one monitor registration behind,
+      # because unmonitor is unusable. Timeouts are an exceptional path, so
+      # these do not accumulate.
+      def terminated?(ractor)
+        probe = Ractor::Port.new
+        !ractor.monitor(probe)
+      ensure
+        probe.close
+      end
+
+      def down_message(ractor, suffix)
+        "#{ractor.name || ractor.inspect} #{suffix}"
+      end
+
+      private_class_method :await, :terminated?, :down_message
+    end
+  end
+end

data/lib/ractor_shepherd/runtime/child_runner.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  module Runtime
+    # What runs inside a child Ractor.
+    #
+    # A `Ractor.new` block cannot see outer locals or self, so the block that
+    # starts a child is a single call to this method with everything passed as
+    # arguments.
+    #
+    # @api private
+    module ChildRunner
+      module_function
+
+      # @param spec [ChildSpec]
+      # @param start_port [Ractor::Port] handshake port, created by the supervisor
+      # @param parent_ref [SupervisorRef, nil]
+      # @param event_port [Ractor::Port, nil]
+      # @param path [String] e.g. "root/jobs/poller"
+      def run(spec, start_port, parent_ref, event_port, path)
+        # Report crashes through events instead of dumping a backtrace on stderr.
+        Thread.current.report_on_exception = false
+        return SupervisorServer.run_as_child(spec, start_port, parent_ref, event_port, path) if
+          spec.type == :supervisor
+
+        run_worker(spec, start_port, parent_ref, event_port, path)
+      end
+
+      def run_worker(spec, start_port, parent_ref, event_port, path)
+        system_port = Ractor::Port.new
+        ctx = Context.new(id: spec.id, path: path, supervisor: parent_ref, event_port: event_port)
+        worker = spec.start.new(*spec.args, **spec.kwargs)
+
+        start_port << Protocol.child_ready(spec.id, system_port, Ractor.current)
+        ctx.start_watcher(system_port)
+
+        reason = :normal
+        begin
+          worker.run(ctx)
+          # Returning after a shutdown request still counts as a shutdown.
+          reason = :shutdown if ctx.shutdown_requested?
+        rescue ShutdownSignal
+          reason = :shutdown
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          reason = e
+          raise
+        ensure
+          call_terminate(worker, reason, ctx)
+        end
+      end
+
+      # An exception from `terminate` turns a clean exit into a crash. When the
+      # worker was already crashing, it is swallowed and recorded as an event so
+      # that the original cause survives.
+      def call_terminate(worker, reason, ctx)
+        worker.terminate(reason)
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        raise unless reason.is_a?(Exception)
+
+        ctx.emit(:terminate_failed, **Core::Event.error_info(e))
+      end
+    end
+  end
+end

data/lib/ractor_shepherd/runtime/child_state.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  module Runtime
+    # A child's mutable state, which lives only inside the supervisor's Ractor.
+    #
+    # @api private
+    class ChildState
+      STATUSES = %i[starting running stopping exited terminated restart_scheduled
+                    start_failed unresponsive removed].freeze
+
+      attr_reader :spec, :backoff
+      attr_accessor :status, :ractor, :stop_port, :ref, :monitor_port, :restart_count
+
+      def initialize(spec, reset_after:)
+        @spec = spec
+        @status = :starting
+        @ractor = nil
+        @stop_port = nil
+        @ref = nil
+        @monitor_port = nil
+        @restart_count = 0
+        @backoff = Core::Backoff.new(spec.restart_delay, reset_after: reset_after)
+      end
+
+      def id = spec.id
+      def type = spec.type
+      def running? = status == :running
+
+      # Let go of the Ractor and its ports once the child has exited.
+      def detach
+        @ractor = nil
+        @stop_port = nil
+        @ref = nil
+        @monitor_port = nil
+      end
+
+      # What the outside world sees.
+      def to_info
+        ChildInfo.new(id: id, type: type, status: status,
+                      ref: running? ? ref : nil, restart_count: restart_count)
+      end
+
+      # What the strategy planner needs.
+      def to_view
+        Core::StrategyPlanner::ChildView.new(id: id, restart: spec.restart, alive: running?)
+      end
+    end
+  end
+end

data/lib/ractor_shepherd/runtime/compat.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  # The Ractor shell: everything that touches Ractors, ports, threads and the clock.
+  module Runtime
+    # Smooths over the Ractor API differences between Ruby 4.0 and 4.1.
+    #
+    # Decisions are made from the shape of a message rather than from
+    # RUBY_VERSION, so development builds such as 4.1.0dev work too.
+    #
+    # @api private
+    module Compat
+      # @raise [UnsupportedRuby] when Ractor::Port is missing
+      def self.check!
+        return if defined?(::Ractor::Port)
+
+        raise UnsupportedRuby,
+              "ractor_shepherd requires Ruby >= 4.0 with Ractor::Port (running #{RUBY_VERSION})"
+      end
+
+      # Normalise a Ractor#monitor notification to :exited or :aborted.
+      #
+      # Ruby 4.0 sends a bare Symbol, Ruby 4.1 sends [ractor, status].
+      def self.monitor_status(msg)
+        case msg
+        in :exited | :aborted then msg
+        in [::Ractor, (:exited | :aborted) => status] then status
+        else raise ProtocolError, "unexpected monitor message: #{msg.inspect}"
+        end
+      end
+
+      # Does Ractor::Port#receive take a timeout: keyword?
+      #
+      # Ruby 4.0 has no such keyword, so every timed wait goes through
+      # Runtime::Timer and Ractor.select. Kept for a future optimisation.
+      def self.native_receive_timeout?
+        ::Ractor::Port.instance_method(:receive).parameters.any? { |kind, name| kind == :key && name == :timeout }
+      end
+    end
+  end
+end

data/lib/ractor_shepherd/runtime/context.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  module Runtime
+    # The handle a worker gets inside its own Ractor.
+    #
+    # It is not shareable. Do not hand it to another Ractor.
+    #
+    # @api private
+    class Context
+      attr_reader :id, :path, :supervisor, :shutdown_reason
+
+      def initialize(id:, path:, supervisor:, event_port:)
+        @id = id
+        @path = path
+        @supervisor = supervisor
+        @event_port = event_port
+        @shutdown = false
+        @shutdown_reason = nil
+        @wake = Thread::Queue.new
+        @seq = 0
+      end
+
+      # Receive one application message.
+      #
+      # @param timeout [Numeric, nil] seconds; nil waits forever
+      # @return [Object, nil] nil on timeout
+      # @raise [ShutdownSignal] once a shutdown has been requested
+      def receive(timeout: nil)
+        raise ShutdownSignal if shutdown_requested?
+
+        timer = nil
+        if timeout
+          @seq += 1
+          timer = Timer.for_current_ractor.after(timeout, Ractor.current, Protocol.timeout(@seq))
+        end
+
+        while true # `loop do` is forbidden here: Ractor::ClosedError < StopIteration
+          message = Ractor.receive
+          raise ShutdownSignal if message == Protocol::SHUTDOWN_SENTINEL
+
+          case message
+          in [Protocol::TIMEOUT, seq]
+            return nil if seq == @seq
+            # A leftover notification from an earlier receive. Drop it and read again.
+          else
+            return message
+          end
+        end
+      ensure
+        timer&.cancel
+      end
+
+      # Has a shutdown been requested?
+      def shutdown_requested? = @shutdown
+
+      # Sleep, but wake immediately if a shutdown arrives.
+      #
+      # @return [Boolean] true if it slept the whole time, false if a shutdown cut it short
+      def sleep(seconds) # rubocop:disable Naming/PredicateMethod
+        return false if shutdown_requested?
+
+        @wake.pop(timeout: seconds).nil?
+      end
+
+      # Publish an application event (as type: :worker_event).
+      def emit(name, **data)
+        emit_system(:worker_event, name: name, data: data)
+      end
+
+      # Publish one of the event types this gem defines.
+      #
+      # @api private
+      def emit_system(type, **data)
+        publish(Core::Event.build(type, supervisor: supervisor_path, at: now, child: id, **data))
+      end
+
+      # Start the thread that waits for a shutdown request.
+      #
+      # A Ractor ends as soon as its main block returns, even with threads still
+      # asleep, so there is nothing to clean up here.
+      def start_watcher(system_port)
+        me = Ractor.current
+        Thread.new(system_port, me) do |port, ractor|
+          _tag, reason = port.receive
+          request_shutdown(reason)
+          ractor.send(Protocol::SHUTDOWN_SENTINEL)
+        rescue Ractor::ClosedError
+          # This Ractor is already on its way out; there is nobody left to wake.
+          nil
+        end
+      end
+
+      # Called from the watcher thread.
+      def request_shutdown(reason)
+        @shutdown_reason = reason
+        @shutdown = true
+        @wake.push(true)
+      end
+
+      # @api private
+      def publish(event)
+        return unless @event_port
+
+        @event_port << event
+      rescue Ractor::ClosedError
+        # The subscriber is gone. Losing observability must not take the child down.
+        nil
+      end
+
+      private
+
+      def supervisor_path = @supervisor&.path || @path
+
+      def now = Process.clock_gettime(Process::CLOCK_REALTIME)
+    end
+  end
+end

data/lib/ractor_shepherd/runtime/protocol.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  module Runtime
+    # Builds and recognises the messages this gem sends.
+    #
+    # Reserved names start with `:"$"`. No message symbol is spelled out
+    # anywhere else in the codebase.
+    #
+    # @api private
+    module Protocol
+      RESERVED_PREFIX = "$"
+
+      CHILD_READY = :"$child_ready"
+      SHUTDOWN = :"$shutdown"
+      CALL = :"$call"
+      REPLY = :"$reply"
+      TIMEOUT = :"$timeout"
+      RESTART_DUE = :"$restart_due"
+      SHUTDOWN_SENTINEL = :"$shutdown_sentinel"
+
+      module_function
+
+      # Child to start port: the child has finished starting.
+      #
+      # @param ref [Ractor, SupervisorRef] the child's own Ractor, or its SupervisorRef
+      # @param stop_port [Ractor::Port] a worker's system port, or a supervisor's control port
+      def child_ready(id, stop_port, ref) = [CHILD_READY, id, stop_port, ref].freeze
+
+      # Parent or API to a child's stop port: please shut down.
+      def shutdown(reason) = [SHUTDOWN, reason].freeze
+
+      # Caller to a control port or a worker's default port.
+      def call(reply_port, request) = [CALL, reply_port, request].freeze
+
+      # Responder to a reply port.
+      def reply(result) = [REPLY, result].freeze
+
+      # Timer to whatever port is being waited on. `seq` tells stale notifications apart.
+      def timeout(seq) = [TIMEOUT, seq].freeze
+
+      # Timer to a supervisor's timer port: a delayed restart is due.
+      def restart_due(generation, ids) = [RESTART_DUE, generation, ids].freeze
+
+      # Is this one of the messages this gem reserves?
+      def reserved?(message)
+        case message
+        when Symbol then message.start_with?(RESERVED_PREFIX)
+        when Array then message[0].is_a?(Symbol) && message[0].start_with?(RESERVED_PREFIX)
+        else false
+        end
+      end
+    end
+  end
+end