odoshi 0.3.0

data/lib/odoshi/cli.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+module Odoshi
+  module CLI
+    USAGE = <<~TXT
+      usage: odoshi run   [config/supervisor.rb]   # start the tree, block until shutdown
+             odoshi check [config/supervisor.rb]   # validate config, print the tree
+             odoshi version
+    TXT
+
+    def self.run(argv)
+      cmd, path = argv[0], (argv[1] || "config/supervisor.rb")
+      case cmd
+      when "run"
+        Telemetry::Subscribers.logger
+        sup = DSL.load_file(path)
+        %w[INT TERM].each { |sig| trap(sig) { sup.stop } }
+        sup.run
+        0
+      when "check"
+        sup = DSL.load_file(path)
+        puts "strategy: #{sup.strategy}"
+        sup.children.each { |c| puts "  #{c.id} (#{c.adapter}, #{c.restart}, shutdown=#{c.shutdown}s)" }
+        0
+      when "version" then puts VERSION; 0
+      else $stderr.puts USAGE; 1
+      end
+    rescue Escalation => e
+      $stderr.puts "odoshi: #{e.message}"; 70 # EX_SOFTWARE — the platform is the final supervisor
+    rescue ConfigError, Errno::ENOENT => e
+      $stderr.puts "odoshi: #{e.message}"; 78 # EX_CONFIG
+    end
+  end
+end

data/lib/odoshi/dsl.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+module Odoshi
+  # Evaluates config/supervisor.rb WITHOUT Rails loaded (DESIGN §9).
+  #
+  #   strategy :rest_for_one
+  #   max_restarts 5, within: 60
+  #   backoff :exponential, base: 1, cap: 30
+  #   child :web,  adapter: :command, cmd: "bundle exec puma -C config/puma.rb"
+  #   child :jobs, adapter: :command, cmd: "bin/jobs"
+  #   supervisor :background do          # DESIGN §3.1: nested subtree with its
+  #     strategy :one_for_all            # own strategy/intensity/backoff
+  #     child :cron, adapter: :command, cmd: "bin/rails cron"
+  #   end
+  class DSL
+    def self.load_file(path)
+      dsl = new
+      dsl.instance_eval(File.read(path), path, 1)
+      dsl.build
+    end
+
+    def initialize(root: true)
+      @root = root
+      @strategy = :one_for_one
+      @intensity = { max_restarts: 5, within: 60 }
+      @backoff = { kind: :exponential, base: 1, cap: 30 }
+      @children = []
+      # DESIGN §5/§9 default; socket nil disables. Only the ROOT supervisor
+      # listens — subtrees never bind their own socket.
+      @socket_path = root ? "tmp/odoshi.sock" : nil
+    end
+
+    def strategy(kind) = @strategy = kind
+    def max_restarts(n, within:) = @intensity = { max_restarts: n, within: within }
+    def backoff(kind, **opts) = @backoff = { kind: kind, **opts }
+
+    def socket(path)
+      raise ConfigError, "socket can only be set on the root supervisor" unless @root
+      @socket_path = path
+    end
+
+    # DESIGN §3.1: `supervisor :background do ... end` creates a subtree — a
+    # :supervisor child whose block supports the full DSL (strategy /
+    # max_restarts / backoff / child, and further nesting). The block is kept
+    # as a builder so every (re)start constructs a FRESH child Supervisor:
+    # RestartIntensity is stateful, and a restarted subtree must start with a
+    # clean intensity window.
+    def supervisor(id, restart: :permanent, shutdown: 30, start_timeout: 30, &block)
+      raise ConfigError, "supervisor #{id.inspect} requires a block" unless block
+      builder = lambda do
+        sub = DSL.new(root: false)
+        sub.instance_eval(&block)
+        sub.build
+      end
+      builder.call # fail fast at config load, not at spawn time
+      # health_interval nil: subtree liveness arrives via link (thread death),
+      # and its internal health is the subtree supervisor's own business — no
+      # probe monitor needed in the parent.
+      @children << ChildSpec.new(id: id, adapter: :supervisor, restart: restart,
+                                 shutdown: shutdown, start_timeout: start_timeout,
+                                 health_interval: nil, opts: { builder: builder })
+    end
+
+    def child(id, adapter:, restart: :permanent, shutdown: 30, start_timeout: 30,
+              health_interval: 5, degraded_restart_after: nil, **opts)
+      @children << ChildSpec.new(id: id, adapter: adapter, restart: restart, shutdown: shutdown,
+                                 start_timeout: start_timeout, health_interval: health_interval,
+                                 degraded_restart_after: degraded_restart_after, opts: opts)
+    end
+
+    def build
+      sup = Supervisor.new(strategy: @strategy,
+                           intensity: RestartIntensity.new(**@intensity),
+                           backoff: Backoff.new(**@backoff),
+                           socket_path: @socket_path)
+      @children.each { |c| sup.add_child(c) }
+      sup
+    end
+  end
+
+  def self.supervise(&block)
+    dsl = DSL.new
+    dsl.instance_eval(&block)
+    dsl.build
+  end
+end

data/lib/odoshi/heartbeat.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+require "socket"
+require "json"
+
+# Deliberately self-contained (PLAN 1.6): any child process can
+#   require "odoshi/heartbeat"
+# without loading the rest of the gem — e.g. from a Rails initializer or a
+# Solid Queue hook — and never Rails itself (hard rule 1 / DESIGN §9).
+module Odoshi
+  # Sends DESIGN §5 NDJSON heartbeats to the supervising socket:
+  #
+  #   beat = Odoshi::Heartbeat.start(id: "jobs")   # => Heartbeat or nil
+  #   beat&.stop
+  #
+  #   Odoshi::Heartbeat.start(id: "jobs", interval: 2,
+  #                             state: -> { queue_backlog_ok? ? "healthy" : "degraded" },
+  #                             meta:  -> { { backlog: backlog_size } })
+  #
+  # Silently a no-op (returns nil) when ODOSHI_SOCK / ODOSHI_TOKEN are
+  # absent — the child is running unsupervised and that must not be an error.
+  #
+  # The beating thread is unkillable by bad input (issue #26): a raising
+  # state/meta lambda falls back to the last good state / empty meta, an
+  # unencodable payload (bad UTF-8) drops down to a bare healthy beat, and
+  # socket failures close the socket (issue #29) and retry next beat. Going
+  # silent is the one thing this thread must never do while its process is
+  # healthy — silence is what gets the child restarted.
+  class Heartbeat
+    # Returns the Heartbeat (so #stop works — issue #23), or nil when
+    # unsupervised.
+    def self.start(id:, interval: 2, state: -> { "healthy" }, meta: -> { {} })
+      new(id: id, interval: interval, state: state, meta: meta).start
+    end
+
+    def initialize(id:, interval: 2, state: -> { "healthy" }, meta: -> { {} })
+      @id, @interval, @state, @meta = id.to_s, interval, state, meta
+      @sock_path, @token = ENV["ODOSHI_SOCK"], ENV["ODOSHI_TOKEN"]
+      @last_state = "healthy"
+    end
+
+    def start
+      return nil unless @sock_path && @token
+      @thread ||= Thread.new { run_loop }
+      self
+    end
+
+    def stop
+      @thread&.kill
+      close_socket
+    end
+
+    def alive? = !!@thread&.alive?
+
+    private
+
+    def run_loop
+      loop do
+        begin
+          payload = build_payload
+          @sock ||= UNIXSocket.new(@sock_path)
+          @sock.puts(payload)
+        rescue StandardError
+          close_socket # supervisor gone or restarting; reconnect next beat
+        end
+        sleep @interval
+      end
+    end
+
+    def build_payload
+      state = safe_state
+      meta = begin
+        @meta.call
+      rescue StandardError
+        {}
+      end
+      encode(state, meta) || encode(state, {}) || encode("healthy", {})
+    end
+
+    def safe_state
+      @last_state = @state.call.to_s
+    rescue StandardError
+      @last_state
+    end
+
+    def encode(state, meta)
+      JSON.generate(id: @id, state: state, ts: Time.now.to_i, token: @token, meta: meta)
+    rescue StandardError
+      nil
+    end
+
+    def close_socket
+      @sock&.close
+      @sock = nil
+    rescue IOError, SystemCallError
+      @sock = nil
+    end
+  end
+end

data/lib/odoshi/orphan_guard.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module Odoshi
+  # PLAN 1.1 orphan prevention: if the supervisor is SIGKILLed, children should
+  # still receive SIGTERM. Linux delivers this via prctl(PR_SET_PDEATHSIG),
+  # armed in the forked child between fork and exec. macOS/BSD have no
+  # equivalent: children there are re-parented to launchd/init and keep running
+  # until the platform supervisor reaps them (documented limitation, README).
+  module OrphanGuard
+    PR_SET_PDEATHSIG = 1
+
+    def self.available?
+      return @available if defined?(@available)
+      @available = RUBY_PLATFORM.include?("linux") && fiddle?
+    end
+
+    def self.fiddle?
+      require "fiddle"
+      true
+    rescue LoadError
+      false
+    end
+
+    # Runs in the forked child, pre-exec. parent_pid is the supervisor's pid at
+    # fork time: pdeathsig is not delivered if the parent died before prctl ran,
+    # so re-check the parent afterwards and exit rather than run orphaned.
+    def self.arm!(parent_pid, signal: "TERM")
+      return false unless available?
+      libc = Fiddle.dlopen(nil)
+      prctl = Fiddle::Function.new(libc["prctl"], [Fiddle::TYPE_INT] * 5, Fiddle::TYPE_INT)
+      armed = prctl.call(PR_SET_PDEATHSIG, Signal.list.fetch(signal), 0, 0, 0).zero?
+      Process.exit!(0) if Process.ppid != parent_pid
+      armed
+    end
+  end
+end

data/lib/odoshi/probe.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+require "socket"
+require "net/http"
+require "uri"
+
+module Odoshi
+  # Passive probes (DESIGN §4.1/§5): a child declared with probe: opts is
+  # :starting until the probe answers, then :healthy. Probes are adapter
+  # plumbing behind health(), not part of the Adapter interface (hard rule 2).
+  #
+  #   probe: { tcp: 5432 }
+  #   probe: { http: "http://127.0.0.1:3000/up" }
+  module Probe
+    CONNECT_TIMEOUT = 0.25
+    READ_TIMEOUT = 0.5
+
+    # true when the probe answers (or the spec declares no probe).
+    def self.answering?(spec)
+      probe = spec.opts[:probe] or return true
+      if (port = probe[:tcp])
+        tcp?(port)
+      elsif (url = probe[:http])
+        http?(url)
+      else
+        raise ConfigError, "#{spec.id}: probe must be {tcp: PORT} or {http: URL}, got #{probe.inspect}"
+      end
+    end
+
+    def self.tcp?(port, host = "127.0.0.1")
+      Socket.tcp(host, port, connect_timeout: CONNECT_TIMEOUT) { true }
+    rescue SystemCallError, IO::TimeoutError
+      false
+    end
+
+    def self.http?(url)
+      uri = URI(url)
+      Net::HTTP.start(uri.host, uri.port, open_timeout: CONNECT_TIMEOUT, read_timeout: READ_TIMEOUT) do |http|
+        http.get(uri.path.empty? ? "/" : uri.path).code.to_i.between?(200, 299)
+      end
+    rescue SystemCallError, IO::TimeoutError, Net::OpenTimeout, Net::ReadTimeout, EOFError
+      false
+    end
+  end
+end

data/lib/odoshi/restart_intensity.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+module Odoshi
+  # OTP restart intensity: more than `max_restarts` within `within` seconds => escalate.
+  class RestartIntensity
+    attr_reader :max_restarts, :within
+
+    def initialize(max_restarts: 5, within: 60, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @max_restarts, @within, @clock = max_restarts, within, clock
+      @events = []
+    end
+
+    # Records a restart. Returns true if the supervisor should escalate (give up).
+    def record!
+      now = @clock.call
+      @events << now
+      @events.reject! { |t| now - t > @within }
+      @events.size > @max_restarts
+    end
+
+    def count = @events.size
+  end
+end

data/lib/odoshi/socket_server.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+require "socket"
+require "json"
+require "securerandom"
+require "fileutils"
+
+module Odoshi
+  # DESIGN §5 active heartbeats + §9 control transport, PLAN 1.4.
+  # Newline-delimited JSON over a Unix socket, mode 0600, per-boot token —
+  # no MessagePack, no length prefixes, no versions (hard rule 4). This wire
+  # format is the contract the Elixir `beam` repo consumes.
+  #
+  # Heartbeat:  {"id":"jobs","state":"healthy","ts":1757700000,"token":"…","meta":{}}
+  # Control:    {"cmd":"restart","id":"jobs","token":"…"}
+  # Any line with a missing or wrong token is dropped without a reply.
+  class SocketServer
+    MAX_LINE = 64 * 1024 # §5: longer lines are malformed and dropped
+    MAX_CONNS = 64       # excess connections are refused (closed immediately)
+
+    attr_reader :path, :token
+
+    def initialize(path:, on_heartbeat:, on_control:)
+      @path, @on_heartbeat, @on_control = path, on_heartbeat, on_control
+      @token = SecureRandom.hex(16)
+      @conns = []
+    end
+
+    # Binds, chmods, and exports ODOSHI_SOCK / ODOSHI_TOKEN so children
+    # spawned afterwards inherit them (DESIGN §9). Call before starting children.
+    def start
+      begin
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.unlink(@path) if File.exist?(@path) # stale socket from a dead boot
+        @server = UNIXServer.new(@path)
+      rescue ArgumentError, SystemCallError => e
+        # e.g. > ~104-byte path on macOS, unwritable dir: config problem, not a crash
+        raise ConfigError, "heartbeat socket #{@path.inspect}: #{e.message}"
+      end
+      @server.listen(128) # default backlog is 5 on macOS; bursts got ECONNREFUSED
+      File.chmod(0o600, @path)
+      ENV["ODOSHI_SOCK"] = @path
+      ENV["ODOSHI_TOKEN"] = @token
+      @acceptor = Thread.new do
+        loop do
+          conn = @server.accept
+          @conns.reject! { |c| !c[:thread].alive? }
+          if @conns.size >= MAX_CONNS
+            close_quietly(conn)
+            next
+          end
+          @conns << { conn: conn, thread: Thread.new { serve(conn) } }
+        rescue IOError, SystemCallError
+          break # server closed during shutdown
+        end
+      end
+    end
+
+    def stop
+      @server&.close
+      @acceptor&.kill
+      @conns.each do |c| # connection threads must not outlive the server
+        c[:thread].kill
+        close_quietly(c[:conn])
+      end
+      @conns.clear
+      File.unlink(@path) if File.exist?(@path)
+    rescue SystemCallError
+      nil
+    end
+
+    private
+
+    def serve(conn)
+      loop do
+        line = conn.gets("\n", MAX_LINE)
+        break if line.nil?
+        unless line.end_with?("\n")
+          # over-long line: memory stays capped at MAX_LINE — discard the rest
+          # of the line, then resume at the next newline
+          line = conn.gets("\n", MAX_LINE) while !line.nil? && !line.end_with?("\n")
+          break if line.nil?
+          next
+        end
+        handle_line(line)
+      end
+    rescue IOError, SystemCallError
+      nil
+    ensure
+      close_quietly(conn)
+    end
+
+    # §5: token, cmd, id, and state are JSON strings; anything else in those
+    # fields is malformed and silently dropped — same as a bad token. A bad
+    # line must never take the connection (or the supervisor) down.
+    def handle_line(line)
+      msg = begin
+        JSON.parse(line)
+      rescue StandardError
+        return
+      end
+      return unless msg.is_a?(Hash) && msg["token"] == @token
+      if msg.key?("cmd")
+        @on_control.call(msg) if msg["cmd"].is_a?(String)
+      elsif msg["id"].is_a?(String) && msg["state"].is_a?(String)
+        @on_heartbeat.call(msg)
+      end
+    end
+
+    def close_quietly(conn)
+      conn.close
+    rescue IOError, SystemCallError
+      nil
+    end
+  end
+end

data/lib/odoshi/strategy.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+module Odoshi
+  # DESIGN §3.3. Given the ordered child ids and the failed id,
+  # return the ordered ids that must be stopped and restarted.
+  module Strategy
+    KINDS = %i[one_for_one rest_for_one one_for_all].freeze
+
+    def self.affected(kind, ordered_ids, failed_id)
+      raise ConfigError, "unknown strategy #{kind}" unless KINDS.include?(kind)
+      idx = ordered_ids.index(failed_id) or raise ArgumentError, "#{failed_id} not in tree"
+      case kind
+      when :one_for_one  then [failed_id]
+      when :rest_for_one then ordered_ids[idx..]
+      when :one_for_all  then ordered_ids.dup
+      end
+    end
+  end
+end