odoshi 0.3.0

data/lib/odoshi/supervisor.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+module Odoshi
+  # DESIGN §3.1 / §3.3. One supervisor, an ordered set of children, one strategy.
+  # Nested supervisors (subtrees) are ordinary children via Adapters::SupervisorAdapter:
+  # a subtree escalating shows up here as a crashed child exit.
+  class Supervisor
+    attr_reader :children, :strategy, :intensity, :backoff
+
+    def initialize(strategy: :one_for_one, intensity: RestartIntensity.new, backoff: Backoff.new,
+                   socket_path: nil)
+      raise ConfigError, "unknown strategy #{strategy}" unless Strategy::KINDS.include?(strategy)
+      @strategy, @intensity, @backoff = strategy, intensity, backoff
+      @children = [] # ordered ChildSpecs
+      @live = {}     # id => { adapter:, handle:, attempts:, generation:, monitor: }
+      @queue = Queue.new
+      @stopping = false
+      @stop_requested = false
+      @heartbeats = {} # id => { at: monotonic ts of last heartbeat, state: reported state }
+      return unless socket_path
+      @socket = SocketServer.new(
+        path: socket_path,
+        # Heartbeats for ids that aren't children of THIS supervisor are
+        # dropped at intake: ghost ids must not grow the table unboundedly
+        # (issue #16/#27). Subtree-grandchild routing is the open flat-id
+        # question — until it's decided, their beats are dropped, not hoarded.
+        on_heartbeat: lambda { |msg|
+          id = msg["id"].to_sym
+          @heartbeats[id] = { at: mono_now, state: msg["state"] } if @children.any? { |c| c.id == id }
+        },
+        on_control: ->(msg) { @queue << { type: :control, cmd: msg["cmd"], id: msg["id"].to_s.to_sym } }
+      )
+    end
+
+    # The per-boot token children must echo in every heartbeat (nil when the
+    # socket is disabled). Exported to children as ODOSHI_TOKEN.
+    def heartbeat_token = @socket&.token
+
+    def add_child(spec)
+      raise ConfigError, "duplicate child id #{spec.id}" if @children.any? { |c| c.id == spec.id }
+      @children << spec
+      self
+    end
+
+    # Blocks until the tree is shut down. Raises Escalation if intensity is exceeded.
+    def run
+      Telemetry.emit(:"supervisor.start", {}, { strategy: strategy, children: ids })
+      @socket&.start # before children, so they inherit ODOSHI_SOCK/_TOKEN
+      @children.each do |spec|
+        break if @stop_requested
+        start_child(spec)
+      end
+      loop do
+        msg = @queue.pop
+        case msg[:type]
+        when :exit then handle_exit(msg[:id], msg[:generation], msg[:status])
+        when :health_dead then handle_health_dead(msg[:id], msg[:generation])
+        when :control then handle_control(msg)
+        when :stop then break
+        end
+      end
+    ensure
+      stop_all
+      @socket&.stop
+      Telemetry.emit(:"supervisor.stop")
+    end
+
+    # Sets the flag first: the main loop may be stuck in a wait_healthy poll
+    # or a backoff sleep for up to start_timeout/backoff seconds, and shutdown
+    # must not wait for those (issue #28 — platforms SIGKILL after their grace
+    # period, which resurrects the orphan problem).
+    def stop
+      @stop_requested = true
+      @queue << { type: :stop }
+    end
+
+    # Public remediation API (DESIGN §7). Over IPC in the real thing; direct call here.
+    def restart!(id)
+      spec = spec_for(id)
+      stop_child(spec)
+      start_child(spec)
+    end
+
+    def ids = @children.map(&:id)
+
+    # Debug/test hook. Not public API.
+    def live_pid(id) = @live.dig(id, :handle)&.pid
+
+    private
+
+    def spec_for(id) = @children.find { |c| c.id == id } || raise(ArgumentError, "no child #{id}")
+
+    def start_child(spec)
+      @heartbeats.delete(spec.id) # a replaced child's heartbeats must not vouch for its successor
+      adapter = Adapter.lookup(spec.adapter).new
+      handle = adapter.spawn(spec)
+      prev = @live[spec.id] || {}
+      generation = (prev[:generation] || 0) + 1
+      @live[spec.id] = { adapter: adapter, handle: handle, attempts: prev[:attempts] || 0, generation: generation }
+      adapter.link(handle) do |status|
+        @queue << { type: :exit, id: spec.id, generation: generation, status: status } unless @stopping
+      end
+      Telemetry.emit(:"child.spawn", {}, { id: spec.id, adapter: spec.adapter, pid: handle.respond_to?(:pid) ? handle.pid : nil })
+      start_monitor(spec, generation) if wait_healthy(spec, adapter, handle) == :healthy
+    end
+
+    # PLAN 1.3: per-child polling thread. :degraded emits telemetry only,
+    # unless degraded_restart_after consecutive reports accumulate; :dead from
+    # a probe (not just SIGCHLD) goes through the exit queue like any crash.
+    def start_monitor(spec, generation)
+      return unless spec.health_interval
+      entry = @live[spec.id]
+      adapter, handle = entry[:adapter], entry[:handle]
+      degraded = 0
+      entry[:monitor] = Thread.new do
+        loop do
+          sleep spec.health_interval
+          break if @stopping || @live.dig(spec.id, :generation) != generation
+          case effective_health(spec, adapter, handle)
+          when :healthy
+            degraded = 0
+            # One healthy interval resets the backoff ladder (#19): a child
+            # that crashes rarely should not converge to permanent max
+            # backoff. Crash-looping children never reach a monitor, so flap
+            # damping is unaffected.
+            entry[:attempts] = 0
+          when :degraded
+            degraded += 1
+            Telemetry.emit(:"child.degraded", { consecutive: degraded }, { id: spec.id })
+            if spec.degraded_restart_after && degraded >= spec.degraded_restart_after
+              @queue << { type: :health_dead, id: spec.id, generation: generation }
+              break
+            end
+          when :dead
+            @queue << { type: :health_dead, id: spec.id, generation: generation }
+            break
+          end
+        end
+      end
+    end
+
+    def wait_healthy(spec, adapter, handle)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + spec.start_timeout
+      loop do
+        return :stopping if @stop_requested # shutdown must not wait out start_timeout (#28)
+        case effective_health(spec, adapter, handle)
+        when :healthy then Telemetry.emit(:"child.healthy", {}, { id: spec.id }); return :healthy
+        when :dead    then return :dead # the exit message arrives via link
+        end
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+          # PLAN 1.2: start_timeout exceeded ⇒ drain. The resulting exit flows
+          # through the normal link → handle_exit path, so it counts as a
+          # crash and the strategy + intensity apply.
+          stop_child(spec)
+          return :timeout
+        end
+        sleep 0.05
+      end
+    end
+
+    HEARTBEAT_STATES = { "starting" => :starting, "healthy" => :healthy,
+                         "degraded" => :degraded, "dead" => :dead }.freeze
+
+    # DESIGN §5/§9: health is active-first. A child that has heartbeated is
+    # judged by heartbeat freshness and its own reported state — missing 3
+    # intervals ⇒ :degraded, 6 ⇒ :dead. Children that never heartbeat fall
+    # back to the adapter's passive probe.
+    def effective_health(spec, adapter, handle)
+      hb = @heartbeats[spec.id]
+      # No heartbeat ⇒ passive probe. A nil health_interval (subtree specs)
+      # also falls through: freshness aging needs an interval, and dividing
+      # by nil crashed the whole tree when a heartbeat named such an id (#25).
+      return adapter.health(handle) unless hb && spec.health_interval
+      missed = (mono_now - hb[:at]) / spec.health_interval
+      return :dead if missed >= 6
+      return :degraded if missed >= 3
+      HEARTBEAT_STATES.fetch(hb[:state], :healthy)
+    end
+
+    def mono_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # DESIGN §7/§9: {"cmd":"restart","id":...} over the socket — the transport
+    # Rails.supervisor.restart! rides later. Unknown commands and ids are
+    # ignored; the token was already checked at the socket layer.
+    def handle_control(msg)
+      return unless msg[:cmd] == "restart"
+      return unless @children.any? { |c| c.id == msg[:id] }
+      restart!(msg[:id])
+    end
+
+    # A monitor thread declared this child unhealthy enough to replace. Drain
+    # it; the resulting real exit flows through link → handle_exit, so the
+    # strategy and intensity apply exactly as for a crash (same path as the
+    # 1.2 start_timeout drain). If the child already exited and was replaced,
+    # the generation guard makes this a no-op.
+    def handle_health_dead(id, generation)
+      entry = @live[id]
+      return if entry.nil? || entry[:generation] != generation
+      stop_child(spec_for(id))
+    end
+
+    def handle_exit(id, generation, status)
+      spec = spec_for(id)
+      entry = @live[id]
+      return if entry.nil? || entry[:generation] != generation # stale exit from a child we already replaced
+
+      uptime = Process.clock_gettime(Process::CLOCK_MONOTONIC) - entry[:handle].started_at
+      Telemetry.emit(:"child.exit", { exit_code: status&.exitstatus, uptime_ms: (uptime * 1000).round }, { id: id })
+      unless spec.restart?(status)
+        # The child is gone for good: keep no stale entry, or stop_all and the
+        # monitor emit spurious drains for a corpse later (issue #20).
+        entry[:monitor]&.kill
+        @live.delete(id)
+        return
+      end
+
+      if intensity.record!
+        Telemetry.emit(:"supervisor.escalate", { restarts: intensity.count }, { within: intensity.within })
+        raise Escalation, "restart intensity exceeded (#{intensity.count} in #{intensity.within}s)"
+      end
+
+      affected = Strategy.affected(strategy, ids, id)
+      # OTP semantics (#14): declaration order encodes dependency, so first
+      # terminate ALL affected children in reverse start order — a
+      # replacement :b must never boot while an old :c that depended on the
+      # dead :b is still running — then restart them in start order.
+      affected.reverse_each do |aid|
+        stop_child(spec_for(aid)) unless aid == id
+      end
+      affected.each do |aid|
+        break if @stop_requested # shutdown preempts the restart fan-out (#28)
+        entry = @live[aid]
+        next unless entry # a temporary/clean-transient sibling is gone for good (#20)
+        attempts = (entry[:attempts] += 1)
+        delay = backoff.delay(attempts)
+        Telemetry.emit(:"child.restart", { backoff_ms: (delay * 1000).round }, { id: aid, attempt: attempts, strategy: strategy })
+        interruptible_sleep(delay)
+        break if @stop_requested
+        start_child(spec_for(aid))
+      end
+    end
+
+    # Backoff must not delay shutdown (#28): sleep in slices, bail on stop.
+    def interruptible_sleep(seconds)
+      deadline = mono_now + seconds
+      while mono_now < deadline
+        return if @stop_requested
+        sleep [0.1, deadline - mono_now].min
+      end
+    end
+
+    def stop_child(spec)
+      entry = @live[spec.id] or return
+      entry[:monitor]&.kill
+      entry[:monitor] = nil
+      Telemetry.emit(:"child.drain", {}, { id: spec.id })
+      return if entry[:adapter].drain(entry[:handle], timeout: spec.shutdown)
+      Telemetry.emit(:"child.kill", {}, { id: spec.id })
+      entry[:adapter].kill(entry[:handle])
+    end
+
+    def stop_all
+      @stopping = true
+      @children.reverse_each { |spec| stop_child(spec) }
+    end
+  end
+end

data/lib/odoshi/telemetry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+require "json"
+
+module Odoshi
+  # Minimal event bus. Event names mirror Elixir :telemetry (DESIGN §6):
+  #   event: [:odoshi, :child, :restart], measurements: {...}, metadata: {...}
+  # A railtie will bridge these into ActiveSupport::Notifications inside children.
+  module Telemetry
+    EVENTS = %i[
+      supervisor.start supervisor.stop supervisor.escalate
+      child.spawn child.healthy child.degraded child.exit child.restart child.drain child.kill
+    ].freeze
+
+    @subscribers = []
+    @mutex = Mutex.new
+
+    class << self
+      def subscribe(&block)
+        @mutex.synchronize { @subscribers << block }
+        block
+      end
+
+      def unsubscribe(block)
+        @mutex.synchronize { @subscribers.delete(block) }
+      end
+
+      def reset!
+        @mutex.synchronize { @subscribers.clear }
+      end
+
+      # name: Symbol like :"child.restart" (flat in Ruby; split on "." for the Elixir side)
+      def emit(name, measurements = {}, metadata = {})
+        raise ArgumentError, "unknown event #{name}" unless EVENTS.include?(name)
+        event = { event: [:odoshi, *name.to_s.split(".").map(&:to_sym)],
+                  measurements: measurements, metadata: metadata,
+                  ts: Process.clock_gettime(Process::CLOCK_REALTIME) }
+        subs = @mutex.synchronize { @subscribers.dup }
+        subs.each do |s|
+          s.call(event)
+        rescue StandardError => e
+          # A subscriber must never break the bus: emit is called from the
+          # supervisor loop and monitor threads, and other subscribers (the
+          # Elixir sidecar exporter, the resilience bridge) must keep
+          # receiving events even when one subscriber raises (resilience#1).
+          warn "[odoshi] telemetry subscriber raised: #{e.class}: #{e.message}"
+        end
+        event
+      end
+    end
+
+    # Default subscribers shipped in v0.1
+    module Subscribers
+      def self.logger(io = $stderr)
+        Telemetry.subscribe do |e|
+          io.puts("[odoshi] #{e[:event].join('.')} #{e[:metadata].inspect} #{e[:measurements].inspect}")
+        end
+      end
+
+      def self.json_lines(io = $stdout)
+        Telemetry.subscribe { |e| io.puts(JSON.generate(e)) }
+      end
+    end
+  end
+end

data/lib/odoshi/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module Odoshi
+  VERSION = "0.3.0"
+end

data/lib/odoshi.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# odoshi: a slim, Rails-free process supervisor with OTP semantics.
+# Nothing under lib/odoshi may require Rails, ActiveSupport, or ActiveRecord (DESIGN §9).
+# The Rails-side bridge (railtie) is a later deliverable and is only ever loaded inside children.
+
+require_relative "odoshi/version"
+
+module Odoshi
+  class Error < StandardError; end
+  class ConfigError < Error; end
+  class Escalation < Error; end # raised when restart intensity is exceeded
+end
+
+require_relative "odoshi/telemetry"
+require_relative "odoshi/child_spec"
+require_relative "odoshi/strategy"
+require_relative "odoshi/restart_intensity"
+require_relative "odoshi/backoff"
+require_relative "odoshi/adapter"
+require_relative "odoshi/probe"
+require_relative "odoshi/orphan_guard"
+require_relative "odoshi/adapters/command"
+require_relative "odoshi/adapters/puma"
+require_relative "odoshi/adapters/solid_queue"
+require_relative "odoshi/socket_server"
+require_relative "odoshi/heartbeat"
+require_relative "odoshi/supervisor"
+require_relative "odoshi/adapters/supervisor_adapter" # after supervisor: wraps a child Supervisor
+require_relative "odoshi/dsl"
+require_relative "odoshi/cli"

data/lib/puma/plugin/odoshi.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+# Puma plugin (DESIGN §4.2 step 2, PLAN 2.5): worker-level visibility for a
+# :puma child, over the §5 heartbeat socket. Enable with `plugin :odoshi`
+# in config/puma.rb.
+#
+# Lives under lib/puma/ (NOT lib/odoshi/) because it may require puma —
+# it is only ever loaded BY puma, so hard rule 1 (the supervisor has zero
+# dependencies) holds. It reuses the frozen heartbeat protocol untouched:
+# worker detail travels in `state` and `meta`, never in new fields.
+#
+# The master heartbeats every ODOSHI_HEARTBEAT_INTERVAL (default 2s):
+#   state = "degraded" while any worker is missing (booted < configured),
+#           "healthy" otherwise (single mode is always "healthy"),
+#   meta  = { workers:, booted:, phase: } (cluster) | { mode: "single" }.
+# The supervisor turns a reported "degraded" into [:odoshi, :child,
+# :degraded] telemetry via its normal health loop — no event added, and no
+# lifecycle change: puma still replaces its own workers.
+require "puma/plugin"
+require "odoshi/heartbeat"
+
+Puma::Plugin.create do
+  def start(launcher)
+    beat = Odoshi::Heartbeat.start(
+      id: ENV["ODOSHI_CHILD_ID"] || "web",
+      interval: Float(ENV.fetch("ODOSHI_HEARTBEAT_INTERVAL", 2)),
+      state: -> { odoshi_state(launcher) },
+      meta: -> { odoshi_meta(launcher) }
+    )
+    launcher.events.on_stopped { beat.stop } if beat
+  end
+
+  private
+
+  # Raising inside the heartbeat thread would silently kill it, so both
+  # lambdas degrade to a safe value instead (stats can raise mid-boot).
+  def odoshi_state(launcher)
+    stats = launcher.stats
+    return "healthy" unless stats[:workers] # single mode
+    stats[:booted_workers] < stats[:workers] ? "degraded" : "healthy"
+  rescue StandardError
+    "starting"
+  end
+
+  def odoshi_meta(launcher)
+    stats = launcher.stats
+    return { mode: "single" } unless stats[:workers]
+    { workers: stats[:workers], booted: stats[:booted_workers], phase: stats[:phase] }
+  rescue StandardError
+    {}
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: odoshi
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- timimsms
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-09-14 00:00:00.000000000 Z
+dependencies: []
+description: A slim supervisor that starts, links, health-checks, and restarts the
+  processes of a Rails app (web, jobs, cable, cron) with OTP strategies.
+email:
+executables:
+- odoshi
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/odoshi
+- lib/odoshi.rb
+- lib/odoshi/adapter.rb
+- lib/odoshi/adapters/command.rb
+- lib/odoshi/adapters/puma.rb
+- lib/odoshi/adapters/solid_queue.rb
+- lib/odoshi/adapters/supervisor_adapter.rb
+- lib/odoshi/backoff.rb
+- lib/odoshi/child_spec.rb
+- lib/odoshi/cli.rb
+- lib/odoshi/dsl.rb
+- lib/odoshi/heartbeat.rb
+- lib/odoshi/orphan_guard.rb
+- lib/odoshi/probe.rb
+- lib/odoshi/restart_intensity.rb
+- lib/odoshi/socket_server.rb
+- lib/odoshi/strategy.rb
+- lib/odoshi/supervisor.rb
+- lib/odoshi/telemetry.rb
+- lib/odoshi/version.rb
+- lib/puma/plugin/odoshi.rb
+homepage: https://github.com/shishi-odoshi/odoshi
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/shishi-odoshi/odoshi
+  source_code_uri: https://github.com/shishi-odoshi/odoshi
+  changelog_uri: https://github.com/shishi-odoshi/odoshi/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/shishi-odoshi/odoshi/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: OTP-style supervision trees for Rails processes
+test_files: []