ractor_shepherd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8166a49f66449c7fdd8d93c65e10e39a58c2e6590179112e2d34667477422c1e
+  data.tar.gz: 0a646565208fb4808b685bac16822a8df1a48b27440d90a7ad7f618b53b7254f
+SHA512:
+  metadata.gz: 8c04a92b8ac6e949373dcc0ab3fa93d9120a8b71bb023edb317c3494ee458c13c55aec93f8ee7fa681b2117e7c785706cd802b8259c4cde861daab8ccbc83742
+  data.tar.gz: f9b15124d25db3eb8ac96e28b164853c4d21727f5cb7a4b4fa83866f0d9dd101bf56cc81e19dd1ae916959f6f26696c97d635ae9a7273c43f91f2db1f060d1bb

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-09-17
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,215 @@
+# ractor_shepherd
+
+Supervise Ruby Ractors the way Erlang/OTP supervisors do. When a child Ractor dies
+with an exception, it is restarted according to a policy you declare; when
+restarting stops helping, the failure is escalated to the supervisor above.
+Supervisors can themselves be children, so a supervision tree is just supervisors
+all the way down.
+
+- Ruby 4.0 or later, and ready for the Ractor API changes in 4.1
+- No runtime dependencies: standard library only
+- The decision logic lives in a layer that never touches Ractors, so it is covered by ordinary unit tests
+
+## Installation
+
+```ruby
+gem "ractor_shepherd"
+```
+
+## A minimal example
+
+```ruby
+require "ractor_shepherd"
+
+class Counter
+  include RactorShepherd::Server
+
+  def initialize(start = 0)
+    super()
+    @count = start
+  end
+
+  def handle_call(message)
+    case message
+    in :get then @count
+    end
+  end
+
+  def handle_cast(message)
+    case message
+    in [:add, n] then @count += n
+    in :crash then raise "boom"
+    end
+  end
+end
+
+events = Ractor::Port.new
+RactorShepherd::EventLogger.start(events) # one line per event on stderr
+
+RactorShepherd.run(name: :root, strategy: :one_for_one, max_restarts: 3, max_seconds: 5,
+                   event_port: events,
+                   children: [RactorShepherd.worker(:counter, Counter, args: [0])]) do |sup|
+  counter = sup.lookup(:counter)
+  counter.cast([:add, 2])
+  counter.call(:get, timeout: 5) #=> 2
+
+  counter.cast(:crash) # it dies, and is restarted with its state back at zero
+end
+```
+
+Runnable examples live in [`examples/`](examples).
+
+| File | What it shows |
+|---|---|
+| `examples/basic.rb` | one_for_one and automatic restarts |
+| `examples/tree.rb` | a supervision tree |
+| `examples/dynamic.rb` | adding and removing children at runtime |
+| `examples/graceful_shutdown.rb` | shutting down cleanly on a signal |
+| `examples/crash_report.rb` | subscribing to events to report why a child died |
+
+## Two kinds of worker
+
+### `RactorShepherd::Worker`, the low level one
+
+You write the loop yourself. `initialize` plays the role of OTP's `init`.
+
+```ruby
+class Poller
+  include RactorShepherd::Worker
+
+  def initialize(url, interval)
+    super()
+    @url = url
+    @interval = interval
+  end
+
+  def run(ctx)
+    until ctx.shutdown_requested?
+      fetch(@url)
+      ctx.sleep(@interval) # returns as soon as a shutdown is requested
+    end
+  end
+
+  def terminate(reason) = nil # optional; reason is :normal, :shutdown, or an exception
+end
+```
+
+What `ctx` (a `Context`) gives you:
+
+| Method | Description |
+|---|---|
+| `id` / `path` | this child's id and path, e.g. `"root/jobs/poller"` |
+| `supervisor` | the parent `SupervisorRef`, which is how you reach siblings |
+| `receive(timeout: nil)` | receive one message; nil on timeout; raises `ShutdownSignal` after a shutdown request |
+| `shutdown_requested?` | has a shutdown been requested? |
+| `sleep(seconds)` | sleep, but wake on shutdown; true if it slept the whole time, false if cut short |
+| `emit(name, **data)` | publish an application event to the event port |
+
+### `RactorShepherd::Server`, the GenServer style one
+
+`run` is already written; you fill in `handle_call` and `handle_cast`. Whatever
+`handle_call` returns becomes the reply.
+
+## Restart strategies
+
+With children `[a, b, c, d]`, when `b` dies:
+
+| Strategy | Stopped (reverse start order) | Started (start order) |
+|---|---|---|
+| `:one_for_one` | nothing | `[b]` |
+| `:one_for_all` | `[d, c, a]` | `[a, b, c, d]` |
+| `:rest_for_one` | `[d, c]` | `[b, c, d]` |
+
+The restart kind (`restart:`) decides whether that child is restarted at all.
+
+| | Exited on its own | Crashed |
+|---|---|---|
+| `:permanent` (default) | restart | restart |
+| `:transient` | leave it stopped | restart |
+| `:temporary` | drop the spec | drop the spec |
+
+Once there have been more than `max_restarts` restarts within `max_seconds`, the
+supervisor gives up: it crashes itself so that its parent decides what happens
+next. At the root, `SupervisorRef#join` raises `SupervisorCrashed`, which is your
+cue to log and `exit(1)` and let systemd or Kubernetes restart the process.
+
+## Things to watch out for
+
+- **Ractors are experimental.** The first `Ractor.new` prints a warning. Silence it
+  with `Warning[:experimental] = false`.
+- **Ractors cannot be killed from outside.** Shutdown is cooperative only. A child
+  spinning on the CPU without looking at `ctx`, or blocked inside a C call, cannot
+  be stopped; after `shutdown_timeout` it is treated as unresponsive.
+- **Symbols starting with `:"$"` are reserved.** Do not start your own messages with one.
+- **Do not call `value` or `join` on a child.** Once another Ractor has taken a
+  Ractor's value, the supervisor can no longer read the exit reason and reports
+  `:unknown`. Restarting still works.
+- **Do not call the supervisor synchronously from `initialize`.** The supervisor is
+  waiting for this child to finish starting, so the call deadlocks until
+  `start_timeout` fires. Look siblings up from `run` instead.
+- **Restarting resets a child's state**, exactly as in Erlang. Anything that must
+  survive belongs outside the child.
+- **Delivery is at-most-once.** A message that arrived just before the child died is lost.
+- **`call` is not for hot paths.** Each one builds a port and a timer thread:
+  roughly 30k req/s against 1.1M msg/s for `cast` (see [bench/RESULTS.md](bench/RESULTS.md)).
+  Use `cast`, or your own `Ractor::Port`, when messages are frequent.
+- **Stopping can take as long as the sum of every child's `shutdown_timeout`**,
+  because children are stopped one at a time in reverse order.
+
+### Gems that are not Ractor safe
+
+Calling a C extension that is not Ractor safe raises `Ractor::UnsafeError`, and
+referencing something unshareable raises `Ractor::IsolationError`. Either way the
+child keeps crashing until the supervisor escalates. This gem attaches a `hint` to
+the event for the exceptions it recognises, so start from the event log.
+
+```text
+ERROR -- [ractor_shepherd] root child_exited child=:a status=:aborted reason=:error
+  error_class="Ractor::IsolationError" hint="the child may be referencing something unshareable, such as a Proc or an IO"
+```
+
+`args:` and `kwargs:` accept only values that survive
+`Ractor.make_shareable(copy: true)`. Procs, Threads and Mutexes do not. Pass plain
+values and hand the behaviour over as a class.
+
+### A note on `Ractor#unmonitor` in Ruby 4.0
+
+Ruby 4.0.6's `Ractor#unmonitor(port)` looks a monitor registration up by port id
+alone and ignores which Ractor created the port. Port ids are a per Ractor
+sequence, so when another Ractor is monitoring the same target, unmonitoring drops
+its registration too. Reproduce it with `ruby spike/unmonitor_id_collision.rb`.
+
+This gem therefore never calls `unmonitor`. One consequence: when a callee dies
+mid-call, the caller finds out after the timeout rather than immediately.
+**Do not call `unmonitor` on a Ractor this gem manages, either.**
+
+## Stopping on a signal
+
+Do not touch ports from inside a trap handler; call `stop` from a thread instead.
+
+```ruby
+Signal.trap("TERM") { Thread.new { sup.stop(:shutdown, timeout: 10) } }
+```
+
+When the main Ractor ends, the process ends and takes every Ractor with it, so
+either use the block form of `RactorShepherd.run` or stop the supervisor from `at_exit`.
+
+## Development
+
+```console
+$ bundle install
+$ bundle exec rake             # rubocop + lint:no_loop + spec + rbs validate
+$ bundle exec rake spec:core   # the unit tests, which use no Ractors
+$ bundle exec rake spec:stress # the stress tests
+$ bundle exec rake spec:isolated # one file per process, to catch hangs
+```
+
+Ractor compatibility is checked with [audition](https://github.com/ruby/audition).
+
+```console
+$ audition lib
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/ractor_shepherd/address.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  # A destination identified by name, returned by `sup.lookup(:jobs, :poller)`.
+  #
+  # It caches what it resolved, so it is **not shareable**: build one per Ractor
+  # that uses it.
+  #
+  # Delivery is at-most-once. A message that arrived just before the child died
+  # is lost.
+  class Address
+    RETRY_INITIAL_DELAY = 0.01
+    RETRY_MAX_DELAY = 0.2
+    RESOLVE_POLL_INTERVAL = 0.01
+
+    attr_reader :path
+
+    def initialize(supervisor, path, retries: 3, resolve_timeout: 1.0)
+      raise InvalidSpec, "lookup needs at least one id" if path.empty?
+
+      @supervisor = supervisor
+      @path = path.freeze
+      @retries = retries
+      @resolve_timeout = resolve_timeout
+      @ractor = nil
+    end
+
+    # The currently cached destination, which may be stale.
+    def ractor
+      @ractor ||= resolve
+    end
+
+    # Throw the cache away and resolve again.
+    def resolve!
+      @ractor = nil
+      ractor
+    end
+
+    # Send without waiting. If the destination has been replaced, resolve again and retry.
+    def cast(message)
+      delay = RETRY_INITIAL_DELAY
+      attempts = 0
+      while true # `loop do` is forbidden here: Ractor::ClosedError < StopIteration
+        begin
+          return send_to(ractor, message)
+        rescue Ractor::ClosedError
+          raise ChildUnavailable, "#{label} is gone" if attempts >= @retries
+
+          attempts += 1
+          Kernel.sleep(delay)
+          delay = [delay * 2, RETRY_MAX_DELAY].min
+          @ractor = nil
+        end
+      end
+    end
+
+    # A synchronous call, for Server children. It never retries on its own,
+    # because the request may not be idempotent.
+    def call(message, timeout: 5)
+      target = ractor
+      raise InvalidOperation, "#{label} is a supervisor; call its SupervisorRef instead" unless target.is_a?(Ractor)
+
+      Runtime::Call.perform(target, target, message, timeout: timeout, down_error: WorkerDown)
+    end
+
+    private
+
+    def label = "#{@supervisor.path}/#{@path.join("/")}"
+
+    def send_to(target, message)
+      raise InvalidOperation, "#{label} is a supervisor; send to its SupervisorRef" unless target.is_a?(Ractor)
+
+      target << message
+      :ok
+    end
+
+    # While the child is being restarted there is nothing to resolve to, so keep
+    # trying until resolve_timeout runs out.
+    def resolve
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @resolve_timeout
+      while true # `loop do` is forbidden here: Ractor::ClosedError < StopIteration
+        found = walk
+        return found if found
+        raise ChildUnavailable, "#{label} is not running" if
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        Kernel.sleep(RESOLVE_POLL_INTERVAL)
+      end
+    end
+
+    def walk
+      current = @supervisor
+      @path[0..-2].each do |segment|
+        current = current.whereis(segment)
+        return nil unless current.is_a?(SupervisorRef)
+      end
+      current.whereis(@path.last)
+    end
+  end
+end

data/lib/ractor_shepherd/core/backoff.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  module Core
+    # Works out how long to wait before restarting a child.
+    #
+    # The consecutive failure count resets to 1 when the child had been up for
+    # at least `reset_after` seconds before dying.
+    #
+    # @api private
+    class Backoff
+      attr_reader :attempt
+
+      # @param spec [nil, Numeric, BackoffSpec]
+      # @param reset_after [Numeric] seconds of uptime after which failures stop counting as consecutive
+      def initialize(spec, reset_after:)
+        @spec = spec
+        @reset_after = reset_after
+        @attempt = 0
+        @started_at = nil
+      end
+
+      # The child came up.
+      def record_start(now)
+        @started_at = now
+      end
+
+      # The child went down, or failed to start.
+      #
+      # @return [Integer] the consecutive failure count
+      def record_failure(now)
+        @attempt = if @started_at && (now - @started_at) >= @reset_after
+                     1
+                   else
+                     @attempt + 1
+                   end
+        @started_at = nil
+        @attempt
+      end
+
+      # @return [Numeric] seconds to wait before the next start; 0 means right away
+      def delay
+        return 0 if attempt.zero?
+
+        case @spec
+        when nil then 0
+        when Numeric then @spec
+        when BackoffSpec then [@spec.max, @spec.initial * (@spec.factor**(attempt - 1))].min
+        else raise ArgumentError, "unknown restart_delay: #{@spec.inspect}"
+        end
+      end
+
+      def reset
+        @attempt = 0
+        @started_at = nil
+      end
+    end
+  end
+end

data/lib/ractor_shepherd/core/event.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  module Core
+    # Builds the event hashes the supervisor and its children publish.
+    #
+    # Events travel between Ractors, so they are always deeply frozen.
+    #
+    # @api private
+    module Event
+      BACKTRACE_LINES = 10
+
+      HINTS = Ractor.make_shareable({
+                                      "Ractor::UnsafeError" =>
+                                        "the child may be calling a C extension that is not Ractor safe",
+                                      "Ractor::IsolationError" =>
+                                        "the child may be referencing something unshareable, such as a Proc or an IO",
+                                      "Ractor::MovedError" =>
+                                        "the child may be referencing an object that was moved to another Ractor"
+                                    })
+
+      module_function
+
+      # @param type [Symbol]
+      # @param supervisor [String] the supervisor's path, e.g. "root/jobs"
+      # @param at [Float] CLOCK_REALTIME
+      # @return [Hash] deeply frozen
+      def build(type, supervisor:, at:, **data)
+        Ractor.make_shareable({ type: type, supervisor: supervisor, at: at }.merge(data), copy: true)
+      end
+
+      # Event keys describing an exception.
+      #
+      # @param error [Exception, Symbol, nil]
+      # @return [Hash]
+      def error_info(error)
+        return {} unless error.is_a?(Exception)
+
+        {
+          error_class: error.class.name,
+          error_message: error.message.to_s,
+          backtrace: (error.backtrace || []).first(BACKTRACE_LINES),
+          hint: hint_for(error)
+        }.compact
+      end
+
+      # @return [String, nil] advice for exceptions we recognise
+      def hint_for(error)
+        klass = error.is_a?(Exception) ? error.class : error
+        klass.ancestors.each do |ancestor|
+          hint = HINTS[ancestor.name]
+          return hint if hint
+        end
+        nil
+      end
+
+      # Normalise an exit reason to :normal, :shutdown, :error or :unknown.
+      def reason_kind(reason)
+        case reason
+        when :normal, :shutdown then reason
+        when Exception then :error
+        else :unknown
+        end
+      end
+    end
+  end
+end

data/lib/ractor_shepherd/core/restart_intensity.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  # Pure logic: no Ractors, no threads, no clock reads. The caller passes the time in.
+  module Core
+    # Give up once there have been more than `max_restarts` restarts within `max_seconds`.
+    #
+    # @api private
+    class RestartIntensity
+      attr_reader :max_restarts, :max_seconds
+
+      def initialize(max_restarts:, max_seconds:)
+        @max_restarts = max_restarts
+        @max_seconds = max_seconds
+        @times = []
+      end
+
+      # Call this once per failure, even when the strategy restarts several children.
+      #
+      # @param now [Float] CLOCK_MONOTONIC
+      # @return [Symbol] :ok or :exceeded
+      def record(now)
+        @times.reject! { |t| now - t > max_seconds }
+        @times << now
+        @times.size > max_restarts ? :exceeded : :ok
+      end
+
+      # @return [Integer] restarts still inside the window
+      def count = @times.size
+    end
+  end
+end

data/lib/ractor_shepherd/core/restart_policy.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  module Core
+    # Decides whether a child should be restarted, from its restart kind and how it exited.
+    #
+    # Exits the supervisor asked for do not go through this table; the shutdown
+    # path handles those.
+    #
+    # @api private
+    module RestartPolicy
+      # | restart \ status | :exited          | :aborted |
+      # |------------------|------------------|----------|
+      # | :permanent       | :restart         | :restart |
+      # | :transient       | :keep_terminated | :restart |
+      # | :temporary       | :remove          | :remove  |
+      TABLE = Ractor.make_shareable({
+                                      permanent: { exited: :restart, aborted: :restart },
+                                      transient: { exited: :keep_terminated, aborted: :restart },
+                                      temporary: { exited: :remove, aborted: :remove }
+                                    })
+
+      # @return [Symbol] :restart, :keep_terminated or :remove
+      def self.decide(restart:, status:, dynamic: false)
+        by_status = TABLE[restart] or raise ArgumentError, "unknown restart: #{restart.inspect}"
+        decision = by_status[status] or raise ArgumentError, "unknown status: #{status.inspect}"
+        # A dynamic supervisor keeps no spec around, so "stay terminated" becomes "forget it".
+        return :remove if dynamic && decision == :keep_terminated
+
+        decision
+      end
+    end
+  end
+end

data/lib/ractor_shepherd/core/strategy_planner.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  module Core
+    # Turns a restart strategy into the concrete list of children to stop and start.
+    #
+    # @api private
+    module StrategyPlanner
+      # The little that the planner needs to know about a child.
+      ChildView = Data.define(:id, :restart, :alive)
+
+      # `terminate` is in stop order (reverse of start order), `start` is in start order.
+      Plan = Data.define(:terminate, :start, :remove)
+
+      # @param children [Array<ChildView>] in start order
+      # @param failed_id [Object] the id of the child that went down
+      # @param strategy [Symbol] :one_for_one, :one_for_all or :rest_for_one
+      # @return [Plan]
+      def self.plan(children:, failed_id:, strategy:)
+        index = children.index { |c| c.id == failed_id }
+        raise ArgumentError, "unknown child: #{failed_id.inspect}" if index.nil?
+
+        case strategy
+        when :one_for_one then Plan.new(terminate: [], start: [failed_id], remove: [])
+        when :one_for_all then for_group(children, children, failed_id)
+        when :rest_for_one then for_group(children, children[index..], failed_id)
+        else raise ArgumentError, "unknown strategy: #{strategy.inspect}"
+        end
+      end
+
+      # @param scope [Array<ChildView>] the children the strategy reaches, in start order
+      def self.for_group(_children, scope, failed_id)
+        affected = scope.reject { |c| c.id == failed_id }
+        terminate = affected.select(&:alive)
+        Plan.new(
+          terminate: terminate.map(&:id).reverse,
+          start: scope.reject { |c| c.restart == :temporary }.map(&:id),
+          remove: terminate.select { |c| c.restart == :temporary }.map(&:id)
+        )
+      end
+      private_class_method :for_group
+    end
+  end
+end

data/lib/ractor_shepherd/errors.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RactorShepherd
+  # Base class for every error this gem raises.
+  #
+  # Exceptions are copied across Ractor boundaries, so keep their instance
+  # variables to simple values: symbols, numbers, frozen strings.
+  class Error < StandardError; end
+
+  # A ChildSpec or SupervisorSpec is invalid.
+  class InvalidSpec < Error; end
+
+  # Loaded on a Ruby that does not meet the requirements.
+  class UnsupportedRuby < Error; end
+
+  # The initial boot failed. The child's exception is the cause.
+  class StartError < Error; end
+
+  # Raised by #join when the supervisor had escalated instead of stopping.
+  class SupervisorCrashed < Error; end
+
+  # Restart intensity exceeded. Raised inside a supervisor and propagated to its parent.
+  class MaxRestartsExceeded < Error; end
+
+  # A child did not acknowledge a shutdown request, or did not finish starting, in time.
+  class ChildUnresponsive < Error; end
+
+  # A synchronous call timed out.
+  class CallTimeout < Error; end
+
+  # The supervisor being called is not running.
+  class SupervisorDown < Error; end
+
+  # The worker being called is not running.
+  class WorkerDown < Error; end
+
+  # No child with that id.
+  class ChildNotFound < Error; end
+
+  # The child exists but has no running Ractor right now (it is being restarted).
+  class ChildUnavailable < Error; end
+
+  # The operation does not apply in the current state.
+  class InvalidOperation < Error; end
+
+  # A dynamic supervisor is already at max_children.
+  class MaxChildrenReached < Error; end
+
+  # An unexpected message shape arrived. Signals a bug.
+  class ProtocolError < Error; end
+
+  # Signals that a shutdown was requested.
+  #
+  # It inherits Exception rather than StandardError so that a plain
+  # `rescue => e` in user code cannot swallow it.
+  class ShutdownSignal < Exception; end # rubocop:disable Lint/InheritException
+end