odoshi 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 470bf921f6ef90d3d251f69d22aea25085c61ff8ca722436a933f7e0a05fb898
+  data.tar.gz: 02e357c5e4191bcbbf2bdd838046a9d6d89fa98c1714db74d60e2e090d32c680
+SHA512:
+  metadata.gz: 3a61f368455b2ef8faae1f6140feaefd4c6c5bbe10b1cc67eeb5f35c905ba10f21dfac0e003141ae3f759c0d40be95a99128cf7060b9f03467c19529c022c3a2
+  data.tar.gz: 5e4bcd0c4385aa3d02a45f64e19c6657126f72efb208b8d514c5577f7140c97cafde64363b6be5ce1d2334969392c4c830702814db3b76d90bf5e5fc503f6f8f

data/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+## v0.3.0 — 2026-09-13 — RENAMED: otp-rails → odoshi
+
+The gem is now **odoshi** (威し — the active half of [shishi-odoshi](https://github.com/shishi-odoshi),
+the self-resetting bamboo fountain). "otp" reads as one-time password in Rubyland; this
+project's OTP was always the Erlang kind. Everything renames — **breaking across the board**:
+
+| was | is |
+|---|---|
+| `gem "otp-rails"` | `gem "odoshi"` |
+| `OtpRails::` / `require "otp_rails/…"` | `Odoshi::` / `require "odoshi/…"` |
+| `otp-rails run` (CLI) | `odoshi run` |
+| `OTP_RAILS_SOCK` / `_TOKEN` / `_CHILD_ID` / `_HEARTBEAT_INTERVAL` | `ODOSHI_SOCK` / `_TOKEN` / `_CHILD_ID` / `_HEARTBEAT_INTERVAL` |
+| telemetry `[:otp_rails, …]` | `[:odoshi, …]` |
+| `plugin :otp_rails` (puma) | `plugin :odoshi` |
+| socket default `tmp/otp-rails.sock` | `tmp/odoshi.sock` |
+
+The Elixir sidecar mirrors the env and telemetry names. Old versions remain published
+under `otp-rails` (0.2.1 is a pointer release); no compatibility shims — rename atomically.
+
+Also in this release:
+- Telemetry subscribers are isolated — one raising subscriber can't break the bus or
+  reach the supervisor loop (QA round 2).
+
+## v0.2.0 — 2026-09-13
+
+**Puma plugin (DESIGN §4.2 step 2)** — `plugin :otp_rails` in `config/puma.rb`: the master
+heartbeats worker-level state over the §5 socket; a missing worker reports `"degraded"`
+(⇒ `child.degraded` telemetry, `meta: {workers, booted, phase}`) while puma replaces it —
+visibility only, no lifecycle change. The `:puma` and `:solid_queue` adapters now export
+`OTP_RAILS_CHILD_ID=<id>` to their children (explicit `env:` wins).
+
+**Hardening from a three-track QA pass** (adversarial review + soak/stress + a Ruby⇄Elixir
+contract harness now permanent in the sidecar's CI):
+- Drain signals the whole process group — shell-wrapped cmds (`"a && b"`) no longer leave
+  their real workload running after a "clean" shutdown, or duplicate it on restart (#24).
+- Fan-out follows OTP: all affected children stop in reverse start order before any
+  restart; declaration-order dependencies hold during `rest_for_one`/`one_for_all` (#14).
+- One spawn path everywhere (fork → setsid → exec): an unspawnable `cmd:` is a child crash
+  (exit 127 → strategy → escalation), not a supervisor crash; identical on macOS/Linux (#15).
+- Socket hardening: 64 KiB line cap, string-typed `token`/`cmd`/`id`/`state`, unknown-id
+  heartbeats dropped at intake, 64-connection cap, listen backlog 128, connection threads
+  torn down on stop, unusable socket path ⇒ exit 78. A well-formed heartbeat naming a
+  subtree id no longer crashes the tree (#25, #27, #16, #17, #30, #31).
+- `stop` is prompt during stuck starts, restart fan-outs, and backoff sleeps — no more
+  blowing platform grace periods (#28). One healthy interval resets the backoff ladder
+  (#19). Non-restarted children leave no stale state or corpse telemetry (#20).
+- `Heartbeat`: the beat thread survives raising/unencodable `state:`/`meta:` lambdas
+  (falls back to last-good state / `{}`), and closes failed sockets — no fd growth while
+  the supervisor is away (#26, #29).
+- DESIGN §5 wire rules documented (token in the example, string fields, line cap, `ts`
+  informational); the Elixir sidecar mirrors them byte-for-byte.
+
+**Breaking:** `OtpRails::Heartbeat.start` returns the `Heartbeat` instance (so `#stop`
+works) instead of the raw Thread; still `nil` when unsupervised (#23).
+
+## v0.1.1 — 2026-09-12
+
+- Gemspec only: author listed as `timimsms`. No code changes.
+
+## v0.1.0 — 2026-09-12
+
+First release: a slim, zero-runtime-dependency, OTP-style process supervisor for the
+processes of a Rails app. The supervisor never loads Rails (DESIGN §9).
+
+- **Supervision core** — `ChildSpec` with `permanent`/`transient`/`temporary` restart
+  semantics; `one_for_one`, `rest_for_one`, `one_for_all` strategies; restart intensity
+  with a sliding window that escalates (exit 70) when exceeded; `none`/`constant`/
+  `exponential` backoff; generation-guarded exit handling (stale exits ignored).
+- **Shutdown correctness** (#1) — `stop_all` drains in reverse start order, waiting per
+  child (SIGTERM, then SIGKILL of the process group after `shutdown:`). Exit codes:
+  0 clean, 70 escalation, 78 config error. Orphan prevention on Linux via
+  `prctl(PR_SET_PDEATHSIG, SIGTERM)`; macOS has no equivalent (documented limitation).
+- **Passive probes** (#2) — `probe: { tcp: PORT }` / `probe: { http: URL }` on `:command`:
+  `:starting` until the probe answers, then `:healthy`. `start_timeout` exceeded ⇒ drain ⇒
+  counts as a crash ⇒ strategy applies.
+- **Periodic health loop** (#3) — per-child monitor at `health_interval` (default 5s);
+  `:degraded` emits telemetry only; `degraded_restart_after: N` drains after N consecutive
+  degraded reports (flows through the crash path, so intensity applies).
+- **`:puma` adapter, beside mode** (#4) — wraps the puma master; health = HTTP `/up` probe;
+  drain = SIGTERM (Puma graceful). `opts[:port]` or a literal `port NNNN` in the config.
+- **Active heartbeat socket** (#5) — Unix socket (default `tmp/otp-rails.sock`, mode 0600),
+  per-boot token via `OTP_RAILS_SOCK` / `OTP_RAILS_TOKEN`; NDJSON heartbeats
+  `{"id","state","ts","token","meta"}`; bad token dropped; 3 missed intervals ⇒ `:degraded`,
+  6 ⇒ `:dead` ⇒ restart; `{"cmd":"restart","id":...}` control messages. This wire protocol
+  is the contract consumed by the Elixir sidecar (`shishi-odoshi/beam`).
+- **`:solid_queue` adapter + heartbeat helper** (#6) — wraps `bin/jobs`; health = active
+  heartbeat, not the DB table. `require "otp_rails/heartbeat"` is Rails-free and
+  self-contained; silently a no-op when unsupervised.
+- **Nested supervisors** (#7) — `supervisor :background do ... end` creates a subtree with
+  its own strategy/intensity/backoff; subtree escalation is an ordinary child exit in the
+  parent; restarted subtrees get a fresh intensity window.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim
+
+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,168 @@
+# odoshi
+
+OTP-style supervision trees for the processes of a Rails app. A slim supervisor — it never
+loads Rails — that starts, links, health-checks, and restarts `web`, `jobs`, `cable`, `cron`
+with `one_for_one` / `rest_for_one` / `one_for_all` strategies, restart intensity, and backoff.
+
+Part of the [shishi-odoshi](https://github.com/shishi-odoshi) org. Design: `docs/DESIGN.md`.
+The Elixir sidecar speaking the same wire protocol lives at
+[shishi-odoshi/beam](https://github.com/shishi-odoshi/beam).
+
+## Install
+
+```ruby
+# Gemfile — the supervisor is its own process; a :supervisor group keeps app boot slim
+group :supervisor do
+  gem "odoshi"
+end
+```
+
+```
+$ bundle install
+$ odoshi version
+```
+
+Zero runtime dependencies. Ruby >= 3.2.
+
+## Quick start
+
+```ruby
+# config/supervisor.rb — plain Ruby, evaluated WITHOUT Rails
+strategy :rest_for_one
+max_restarts 5, within: 60
+backoff :exponential, base: 1, cap: 30
+
+child :web,  adapter: :puma, port: 3000
+child :jobs, adapter: :solid_queue, shutdown: 60
+child :cron, adapter: :command, cmd: "bin/rails cron", restart: :transient
+```
+
+```
+$ odoshi check config/supervisor.rb   # validate config, print the tree
+$ odoshi run   config/supervisor.rb   # supervise (Ctrl-C drains and stops)
+```
+
+## Config reference
+
+Top-level directives in `config/supervisor.rb`:
+
+| Directive | Default | Meaning |
+|---|---|---|
+| `strategy KIND` | `:one_for_one` | `:one_for_one` restarts only the failed child; `:rest_for_one` also restarts children declared after it; `:one_for_all` restarts every child |
+| `max_restarts N, within: S` | `5, within: 60` | Sliding-window restart intensity; exceeding it escalates (exit 70) |
+| `backoff KIND, **opts` | `:exponential, base: 1, cap: 30` | `:none`, `:constant`, or `:exponential` delay between restarts |
+| `socket PATH` | `"tmp/odoshi.sock"` | Heartbeat/control Unix socket; `socket nil` disables it |
+| `child ID, adapter:, **opts` | — | Declares a child; declaration order is start order |
+| `supervisor ID do ... end` | — | Nested subtree with its own strategy/intensity/backoff; subtree escalation is an ordinary child exit in the parent |
+
+Per-child options:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `restart:` | `:permanent` | `:permanent` always restarts; `:transient` restarts only on non-zero exit; `:temporary` never restarts |
+| `shutdown:` | `30` | Seconds to wait after SIGTERM before SIGKILL of the child's process group |
+| `start_timeout:` | `30` | Seconds to reach `:healthy`; exceeding it drains the child and counts as a crash |
+| `health_interval:` | `5` | Seconds between health checks (and the unit for heartbeat freshness) |
+| `degraded_restart_after:` | `nil` | N consecutive `:degraded` reports ⇒ drain and restart (counts toward intensity) |
+
+Adapters:
+
+- **`:command`** — any command. `cmd:` (required), `env:`, `spawn_opts:`, and optional
+  `probe: { tcp: PORT }` or `probe: { http: "http://127.0.0.1:3000/up" }` — the child is
+  `:starting` until the probe answers, `:degraded` if it stops answering later.
+- **`:puma`** (beside mode) — wraps the puma master. `config:` (default `config/puma.rb`),
+  `port:` (or a literal `port NNNN` line in the config). Health = HTTP probe of `/up`;
+  drain = SIGTERM (Puma's graceful stop).
+- **`:solid_queue`** — wraps `bin/jobs` (`cmd:` overrides). Health = the active heartbeat
+  below, never the `solid_queue_processes` table.
+
+For worker-level visibility on a cluster-mode `:puma` child, add the plugin to
+`config/puma.rb`:
+
+```ruby
+plugin :odoshi
+```
+
+The master then heartbeats worker state over the socket: any missing worker is reported
+`"degraded"` (⇒ `[:odoshi, :child, :degraded]` telemetry, `meta: {workers:, booted:,
+phase:}`) while puma replaces the worker itself — visibility only, no lifecycle change.
+Both adapters export `ODOSHI_CHILD_ID` so plugins and hooks heartbeat under the right id.
+
+## Health & heartbeats
+
+Passive children are probed (PID, TCP, HTTP). Active children report themselves: the
+supervisor listens on a Unix socket (mode 0600) and exports `ODOSHI_SOCK` /
+`ODOSHI_TOKEN` to every child. Heartbeats are newline-delimited JSON:
+
+```json
+{"id":"jobs","state":"healthy","ts":1757700000,"token":"…","meta":{"backlog":0}}
+```
+
+A child that has heartbeated is judged by heartbeat freshness: 3 missed `health_interval`s
+⇒ `:degraded`, 6 ⇒ `:dead` ⇒ the strategy applies. Wrong token, non-string fields, or
+lines over 64 KiB ⇒ silently dropped. The same socket accepts
+`{"cmd":"restart","id":"jobs","token":"…"}` — a control restart is deliberate remediation
+(DESIGN §7: restarting is a feature), so it does not count toward restart intensity.
+
+From any child process (a Rails initializer, a Solid Queue hook — no Rails required):
+
+```ruby
+require "odoshi/heartbeat"   # loads nothing else
+Odoshi::Heartbeat.start(id: "jobs")  # no-op when running unsupervised
+```
+
+## Telemetry reference
+
+Event names follow `[:odoshi, :subject, :action]`, mirroring Elixir `:telemetry` so the
+sidecar can forward them unchanged. This list is a published contract:
+
+```
+[:odoshi, :supervisor, :start]     metadata: {strategy, children}
+[:odoshi, :supervisor, :stop]
+[:odoshi, :supervisor, :escalate]  measurements: {restarts}  metadata: {within}
+[:odoshi, :child, :spawn]          metadata: {id, adapter, pid}
+[:odoshi, :child, :healthy]        metadata: {id}
+[:odoshi, :child, :degraded]       measurements: {consecutive}  metadata: {id}
+[:odoshi, :child, :exit]           measurements: {exit_code, uptime_ms}  metadata: {id}
+[:odoshi, :child, :restart]        measurements: {backoff_ms}  metadata: {id, attempt, strategy}
+[:odoshi, :child, :drain]          metadata: {id}
+[:odoshi, :child, :kill]           metadata: {id}  (drain timed out)
+```
+
+Subscribe in-process with `Odoshi::Telemetry.subscribe { |event| ... }`; a logger
+subscriber and a JSON-lines exporter ship by default (`Telemetry::Subscribers`).
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Clean stop (SIGINT/SIGTERM, all children drained) |
+| `70` | Restart intensity exceeded — the supervisor escalated (EX_SOFTWARE). The platform (Kamal/K8s/Heroku/launchd) is the final supervisor and should restart on non-zero |
+| `78` | Configuration error (EX_CONFIG) |
+
+## Shutdown semantics
+
+- `stop_all` drains children in **reverse start order**, waiting for each child to exit
+  (up to its `shutdown:` timeout, then SIGKILL of its process group) before draining the next.
+- Orphan prevention: on Linux, children are armed with `prctl(PR_SET_PDEATHSIG, SIGTERM)`
+  between fork and exec, so they receive SIGTERM even if the supervisor is SIGKILLed.
+  **macOS/BSD limitation:** no parent-death signal exists there; a SIGKILLed supervisor
+  orphans its children to launchd/init and they keep running. Mitigation: the platform
+  restarts the supervisor; each child runs in its own session/process group, so stale
+  orphans are findable and killable by pgid.
+- macOS also caps Unix socket paths at ~104 bytes — keep `socket PATH` short.
+- Compound commands (`cmd: "a && b"`) run under an `sh` wrapper. Drain and kill signal the
+  whole process group, so supervised shutdown covers the real workload — but SIGKILL-of-
+  the-supervisor orphan prevention (pdeathsig) arms only the wrapper: on Linux the wrapper
+  gets SIGTERM and its children are orphaned. Prefer single-exec commands for children
+  that must never outlive the supervisor.
+
+## Development
+
+```
+bundle exec rake test                        # full suite (real processes, no mocks)
+ruby -Ilib -Itest test/supervisor_kill_test.rb
+exe/odoshi check examples/supervisor.rb
+```
+
+`docs/PLAN.md` is the backlog; `docs/DESIGN.md` is the frozen design.

data/exe/odoshi

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+require_relative "../lib/odoshi"
+exit Odoshi::CLI.run(ARGV)

data/lib/odoshi/adapter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+module Odoshi
+  # DESIGN §4. Exactly four operations (+ kill as last resort). Adapters never talk to each other.
+  class Adapter
+    REGISTRY = {}
+
+    def self.register(name, klass) = REGISTRY[name] = klass
+    def self.lookup(name) = REGISTRY.fetch(name) { raise ConfigError, "no adapter registered as #{name.inspect}" }
+
+    # @return [Object] opaque handle
+    def spawn(spec) = raise NotImplementedError
+    # Register a one-shot callback: block.call(exit_status)
+    def link(handle, &on_exit) = raise NotImplementedError
+    # @return [:starting, :healthy, :degraded, :dead]
+    def health(handle) = raise NotImplementedError
+    # Stop accepting work, finish in-flight, exit. Return true if exited within timeout.
+    def drain(handle, timeout:) = raise NotImplementedError
+    # Last resort after drain times out.
+    def kill(handle) = raise NotImplementedError
+  end
+end

data/lib/odoshi/adapters/command.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+module Odoshi
+  module Adapters
+    # DESIGN §4.1 :command — arbitrary command. Health = PID alive (+ optional probe, TODO).
+    class Command < Adapter
+      Handle = Struct.new(:pid, :spec, :started_at, :exit_status, :waiter, :healthy_once)
+
+      def spawn(spec)
+        cmd = spec.opts.fetch(:cmd) { raise ConfigError, "#{spec.id}: :command adapter requires cmd:" }
+        env = spec.opts.fetch(:env, {}).transform_keys(&:to_s)
+        spawn_opts = spec.opts.fetch(:spawn_opts, {})
+        # One spawn path on every platform (#15): fork → setsid → exec, with
+        # exec failure becoming exit 127 through the normal link → crash →
+        # strategy machinery. Process.spawn raised Errno::ENOENT into the
+        # supervisor loop for a bad cmd on macOS (whole tree crashed, exit 1)
+        # while the Linux fork path restart-looped to escalation (exit 70).
+        parent = Process.pid
+        pid = Process.fork do
+          Process.setsid # own session ⇒ own pgroup (drain/kill signal the group)
+          OrphanGuard.arm!(parent)
+          begin
+            Process.exec(env, cmd, **spawn_opts)
+          rescue StandardError
+            Process.exit!(127)
+          end
+        end
+        Handle.new(pid, spec, Process.clock_gettime(Process::CLOCK_MONOTONIC), nil, nil)
+      end
+
+      def link(handle, &on_exit)
+        handle.waiter = Thread.new do
+          _, status = Process.wait2(handle.pid)
+          handle.exit_status = status
+          on_exit.call(status)
+        rescue Errno::ECHILD
+          on_exit.call(nil)
+        end
+      end
+
+      def health(handle)
+        return :dead if handle.exit_status
+        Process.kill(0, handle.pid)
+        if Probe.answering?(handle.spec)
+          handle.healthy_once = true
+          :healthy
+        elsif handle.healthy_once
+          :degraded # was healthy, probe stopped answering, PID still alive (§5)
+        else
+          :starting
+        end
+      rescue Errno::ESRCH
+        :dead
+      end
+
+      def drain(handle, timeout:)
+        # Signal the whole process group, not just handle.pid: children are
+        # group leaders (setsid / pgroup: true), and a shell-wrapped cmd
+        # ("a && b") is an sh wrapper whose real workload is a grandchild in
+        # that group — TERM to the wrapper alone orphans the workload while
+        # reporting a clean drain (issue #24).
+        group_signal("TERM", handle.pid)
+        handle.waiter&.join(timeout)
+        !handle.exit_status.nil?
+      rescue Errno::ESRCH
+        true
+      end
+
+      def kill(handle)
+        Process.kill("KILL", -handle.pid) # whole process group
+        handle.waiter&.join(2)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      private
+
+      # TERM the group; fall back to the pid alone if the group is already
+      # gone by the time we signal (pure pid death races to the outer ESRCH).
+      def group_signal(sig, pid)
+        Process.kill(sig, -pid)
+      rescue Errno::ESRCH
+        Process.kill(sig, pid)
+      end
+    end
+  end
+  Adapter.register(:command, Adapters::Command)
+end

data/lib/odoshi/adapters/puma.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+module Odoshi
+  module Adapters
+    # DESIGN §4.1 / §4.2 step 1 — :puma in "beside" mode: one opaque child
+    # wrapping the puma master. Health = HTTP probe of /up (the Rails 7.1+
+    # default endpoint) on the bound port; drain = SIGTERM, which is Puma's
+    # graceful shutdown — exactly Command#drain, so it is inherited unchanged,
+    # as are link and kill.
+    #
+    # The whole adapter is Command with a derived spec: spawn builds the puma
+    # command line and injects a probe: { http: ".../up" } opt, so health()
+    # rides the PLAN 1.2 Probe path with no new code — :starting until /up
+    # answers 2xx, then :healthy; :dead when the PID goes.
+    #
+    # opts:
+    #   config:     puma config file path (default "config/puma.rb")
+    #   port:       the bound port. When absent, a literal `port NNNN` line is
+    #               parsed from the config file; neither ⇒ ConfigError.
+    #   env:, spawn_opts:  passed through to Command verbatim.
+    #   (cmd: and probe: are owned by this adapter and overwritten.)
+    class Puma < Command
+      DEFAULT_CONFIG = "config/puma.rb"
+      HEALTH_PATH = "/up"
+
+      def spawn(spec)
+        super(command_spec(spec))
+      end
+
+      private
+
+      def command_spec(spec)
+        config = spec.opts.fetch(:config, DEFAULT_CONFIG)
+        port = resolve_port(spec, config)
+        ChildSpec.new(
+          id: spec.id, adapter: spec.adapter, restart: spec.restart,
+          shutdown: spec.shutdown, start_timeout: spec.start_timeout,
+          opts: spec.opts.merge(
+            cmd: "bundle exec puma -C #{config}",
+            probe: { http: "http://127.0.0.1:#{port}#{HEALTH_PATH}" },
+            # Tag the child so the odoshi puma plugin (and any app hook)
+            # heartbeats under the right id; explicit env still wins.
+            env: { "ODOSHI_CHILD_ID" => spec.id.to_s }.merge(spec.opts.fetch(:env, {}))
+          )
+        )
+      end
+
+      # opts[:port] wins; else a literal `port NNNN` line in the config file.
+      # Anything fancier (ENV/ERB in the config) must pass opts[:port].
+      def resolve_port(spec, config)
+        return Integer(spec.opts[:port]) if spec.opts[:port]
+        literal = File.file?(config) && File.read(config)[/^\s*port\s+(\d+)/, 1]
+        return Integer(literal) if literal
+        raise ConfigError,
+              "#{spec.id}: :puma needs opts[:port] or a literal `port NNNN` line in #{config}"
+      end
+    end
+  end
+  Adapter.register(:puma, Adapters::Puma)
+end

data/lib/odoshi/adapters/solid_queue.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+module Odoshi
+  module Adapters
+    # DESIGN §4.1 / §9 — :solid_queue wraps the Solid Queue supervisor
+    # (`bin/jobs`). Health is the ACTIVE heartbeat (§5), NOT the
+    # solid_queue_processes table: the app sends heartbeats via the tiny
+    # Rails-free hook, e.g. from an initializer:
+    #
+    #   require "odoshi/heartbeat"
+    #   Odoshi::Heartbeat.start(id: "jobs")
+    #
+    # Once the first heartbeat arrives the supervisor judges the child by
+    # heartbeat freshness (3 missed intervals ⇒ :degraded, 6 ⇒ :dead);
+    # until then it falls back to this adapter's passive PID health,
+    # inherited from Command — as are link, drain (SIGTERM, which Solid
+    # Queue handles gracefully), and kill.
+    #
+    # opts:
+    #   cmd:  the jobs command (default "bin/jobs")
+    #   env:, spawn_opts:  passed through to Command verbatim.
+    class SolidQueue < Command
+      DEFAULT_CMD = "bin/jobs"
+
+      def spawn(spec)
+        super(command_spec(spec))
+      end
+
+      private
+
+      def command_spec(spec)
+        ChildSpec.new(
+          id: spec.id, adapter: spec.adapter, restart: spec.restart,
+          shutdown: spec.shutdown, start_timeout: spec.start_timeout,
+          opts: spec.opts.merge(
+            cmd: spec.opts.fetch(:cmd, DEFAULT_CMD),
+            # Tag the child so the Heartbeat hook picks up its id from env;
+            # explicit env still wins.
+            env: { "ODOSHI_CHILD_ID" => spec.id.to_s }.merge(spec.opts.fetch(:env, {}))
+          )
+        )
+      end
+    end
+  end
+  Adapter.register(:solid_queue, Adapters::SolidQueue)
+end

data/lib/odoshi/adapters/supervisor_adapter.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+module Odoshi
+  module Adapters
+    # DESIGN §3.1 nested supervisors. A subtree is just another child of the
+    # parent: this pseudo-adapter runs a child Supervisor on a Thread and maps
+    # the four adapter operations onto it. Escalation inside the subtree
+    # terminates the thread, which surfaces to the parent as a crashed exit —
+    # the parent then applies ITS strategy/intensity to the subtree child
+    # (restart the whole subtree, etc.), exactly per OTP semantics.
+    #
+    # opts:
+    #   builder: a Proc returning a FRESH Odoshi::Supervisor each call.
+    #            A restarted subtree must not inherit the old subtree's
+    #            RestartIntensity window (it is stateful), so spawn re-invokes
+    #            the builder on every (re)start instead of reusing an instance.
+    class SupervisorAdapter < Adapter
+      # Duck-types the two things the tree asks of an exit status:
+      # #exitstatus (telemetry) and #success? (ChildSpec#restart? semantics).
+      Status = Struct.new(:exitstatus) do
+        def success? = exitstatus == 0
+      end
+
+      Handle = Struct.new(:sub, :thread, :started_at, :exit_status, :waiter, :killed)
+
+      def spawn(spec)
+        builder = spec.opts.fetch(:builder) do
+          raise ConfigError, "#{spec.id}: :supervisor adapter requires builder: (a proc returning a fresh Supervisor)"
+        end
+        sub = builder.call
+        raise ConfigError, "#{spec.id}: builder must return an Odoshi::Supervisor" unless sub.is_a?(Supervisor)
+        thread = Thread.new { sub.run }
+        # Escalation out of a subtree is an expected, handled exit path — the
+        # waiter converts it into a crashed status. Don't let Ruby dump it.
+        thread.report_on_exception = false
+        Handle.new(sub, thread, Process.clock_gettime(Process::CLOCK_MONOTONIC), nil, nil, false)
+      end
+
+      def link(handle, &on_exit)
+        handle.waiter = Thread.new do
+          status =
+            begin
+              handle.thread.join # re-raises whatever terminated the subtree
+              Status.new(handle.killed ? nil : 0)
+            rescue Escalation
+              Status.new(70) # crashed: intensity exceeded inside the subtree
+            rescue StandardError
+              Status.new(1)  # crashed: unexpected error in the subtree loop
+            end
+          handle.exit_status = status
+          on_exit.call(status)
+        end
+      end
+
+      # The subtree's internal health is its own supervisor's business; from
+      # the parent's seat the subtree is healthy while its loop is running.
+      # Death also arrives via link, so parents normally give subtree specs
+      # health_interval: nil (the DSL does) and skip the probe monitor.
+      def health(handle)
+        handle.thread.alive? ? :healthy : :dead
+      end
+
+      # Clean stop: the subtree's run loop breaks and its `ensure stop_all`
+      # drains the subtree's own children (reverse order) before the thread
+      # exits — so by the time this returns true, no subtree PIDs remain.
+      def drain(handle, timeout:)
+        handle.sub.stop
+        joined =
+          begin
+            handle.thread.join(timeout)
+          rescue StandardError
+            handle.thread # join re-raised => the thread has terminated
+          end
+        !joined.nil?
+      end
+
+      # Last resort. Thread#kill still runs the subtree's `ensure stop_all`;
+      # if even that wedges, best-effort drain the subtree's children directly
+      # so no grandchild PIDs are orphaned.
+      def kill(handle)
+        handle.killed = true
+        handle.thread.kill
+        joined =
+          begin
+            handle.thread.join(2)
+          rescue StandardError
+            handle.thread
+          end
+        handle.sub.send(:stop_all) if joined.nil? # loop wedged: drain grandchildren ourselves
+      rescue StandardError
+        nil
+      end
+    end
+  end
+  Adapter.register(:supervisor, Adapters::SupervisorAdapter)
+end

data/lib/odoshi/backoff.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+module Odoshi
+  class Backoff
+    def initialize(kind: :exponential, base: 1.0, cap: 30.0)
+      @kind, @base, @cap = kind, base.to_f, cap.to_f
+    end
+
+    # attempt is 1-based
+    def delay(attempt)
+      case @kind
+      when :none        then 0.0
+      when :constant    then @base
+      when :exponential then [@base * (2**(attempt - 1)), @cap].min
+      else raise ConfigError, "unknown backoff #{@kind}"
+      end
+    end
+  end
+end

data/lib/odoshi/child_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+module Odoshi
+  # DESIGN §3.2
+  class ChildSpec
+    RESTART_KINDS = %i[permanent transient temporary].freeze
+
+    attr_reader :id, :adapter, :restart, :shutdown, :start_timeout, :health_interval,
+                :degraded_restart_after, :opts
+
+    def initialize(id:, adapter:, restart: :permanent, shutdown: 30, start_timeout: 30,
+                   health_interval: 5, degraded_restart_after: nil, opts: {})
+      raise ConfigError, "child id must be a Symbol" unless id.is_a?(Symbol)
+      raise ConfigError, "restart must be one of #{RESTART_KINDS}" unless RESTART_KINDS.include?(restart)
+      @id, @adapter, @restart, @shutdown, @start_timeout, @opts =
+        id, adapter, restart, shutdown, start_timeout, opts
+      @health_interval, @degraded_restart_after = health_interval, degraded_restart_after
+    end
+
+    # Should this child be restarted given how it exited? (OTP semantics)
+    def restart?(exit_status)
+      case restart
+      when :permanent then true
+      when :transient then !normal_exit?(exit_status)
+      when :temporary then false
+      end
+    end
+
+    def normal_exit?(status)
+      return false if status.nil?
+      status.respond_to?(:success?) ? status.success? : status.to_i.zero?
+    end
+  end
+end