odoshi 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 470bf921f6ef90d3d251f69d22aea25085c61ff8ca722436a933f7e0a05fb898
-  data.tar.gz: 02e357c5e4191bcbbf2bdd838046a9d6d89fa98c1714db74d60e2e090d32c680
+  metadata.gz: 37c7e2f930a701add4d309f524f1bb3f929e67f2df29f124400749fd2454caea
+  data.tar.gz: 855cdc3692d053be6a91252f92019b082cc09207844fa4830613c3901e63c5f1
 SHA512:
-  metadata.gz: 3a61f368455b2ef8faae1f6140feaefd4c6c5bbe10b1cc67eeb5f35c905ba10f21dfac0e003141ae3f759c0d40be95a99128cf7060b9f03467c19529c022c3a2
-  data.tar.gz: 5e4bcd0c4385aa3d02a45f64e19c6657126f72efb208b8d514c5577f7140c97cafde64363b6be5ce1d2334969392c4c830702814db3b76d90bf5e5fc503f6f8f
+  metadata.gz: 05c598c1dc53ec1c7299b99243e094a6b311a086ab64bef72765e60f896d23e8858bfc2110882d9513acd03a5e43847a7f79fbaf41a9a74d10d23dde58b9f239
+  data.tar.gz: 9cf2c1e96c32ffeda5639584d6092c4f2ec22935e856b0bfd4be7979cd50a6148966e051bec4c67a2a24119918f3d1a649689bc8bcb106ef81ad0e868ca9e953

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v0.3.1 — 2026-09-14
+
+Two fixes from odoshi-bench findings:
+- **Puma plugin heartbeat no longer masks a wedged app (#49).** Under §5 active-first
+  health a "healthy" heartbeat out-votes a failing probe; the plugin's stats-only
+  heartbeat therefore silently disabled wedge detection on any :puma child running it.
+  The plugin now reports the WORSE of worker topology and a /up probe on the first tcp
+  bind (`ODOSHI_HEALTH_URL` overrides; unix-only binds fall back to topology-only), and
+  `meta` gains `up: true/false`.
+- **Immediate first restart for `:exponential` backoff (odoshi-template#1).** OTP
+  convention: a one-off crash costs no delay — the ladder starts at `base` from the
+  second consecutive attempt (crash-loops stay bounded by intensity, and a healthy
+  interval resets attempts). Benchmarked recovery drops by ~1s under the default config.
+
 ## 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),

data/README.md

@@ -50,7 +50,7 @@ Top-level directives in `config/supervisor.rb`:
 |---|---|---|
 | `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 |
+| `backoff KIND, **opts` | `:exponential, base: 1, cap: 30` | `:none`, `:constant`, or `:exponential` delay between restarts. `:exponential`'s FIRST restart is immediate (OTP convention); the ladder starts at `base` from the second consecutive attempt |
 | `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 |

data/lib/odoshi/backoff.rb

@@ -5,12 +5,17 @@ module Odoshi
       @kind, @base, @cap = kind, base.to_f, cap.to_f
     end
 
-    # attempt is 1-based
+    # attempt is 1-based. :exponential follows OTP convention: the FIRST
+    # restart is immediate — a one-off crash costs no delay (crash-loops are
+    # bounded by restart intensity, and a healthy interval resets attempts) —
+    # and the ladder starts at `base` from the second consecutive attempt.
+    # :constant stays constant every time: explicit is explicit.
+    # (odoshi-template#1: `base: 1` was putting a ~1s floor on every recovery.)
     def delay(attempt)
       case @kind
       when :none        then 0.0
       when :constant    then @base
-      when :exponential then [@base * (2**(attempt - 1)), @cap].min
+      when :exponential then attempt <= 1 ? 0.0 : [@base * (2**(attempt - 2)), @cap].min
       else raise ConfigError, "unknown backoff #{@kind}"
       end
     end

data/lib/odoshi/version.rb

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

data/lib/puma/plugin/odoshi.rb

@@ -8,17 +8,29 @@
 # 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 master heartbeats every ODOSHI_HEARTBEAT_INTERVAL (default 2s). The
+# reported state is the WORSE of two views (issue #49 — a heartbeat must
+# never vouch for an app its own health endpoint says is sick, because
+# active heartbeats out-vote passive probes in the supervisor's §5
+# active-first health):
+#   - worker topology: "degraded" while any worker is missing (booted <
+#     configured); single mode has no workers to count;
+#   - app health: /up probed on the first tcp bind — "starting" until the
+#     first 2xx, "degraded" if it stops answering 2xx afterwards.
+#   meta = { workers:, booted:, phase: } (cluster) | { mode: "single" },
+#   plus up: true/false once a tcp bind is probeable.
+# ODOSHI_HEALTH_URL overrides the probe URL (e.g. unix-socket binds);
+# with no tcp bind and no override, state falls back to topology only.
 # 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"
+require "odoshi/probe"
 
 Puma::Plugin.create do
+  HEALTH_PATH = "/up"
+
   def start(launcher)
     beat = Odoshi::Heartbeat.start(
       id: ENV["ODOSHI_CHILD_ID"] || "web",
@@ -35,17 +47,49 @@ Puma::Plugin.create do
   # 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"
+    worker_missing = stats[:workers] && stats[:booted_workers] < stats[:workers]
+    return "degraded" if worker_missing
+    case odoshi_up_state(launcher)
+    when :down then "degraded"
+    when :booting then "starting"
+    else "healthy"
+    end
   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] }
+    meta = stats[:workers] ? { workers: stats[:workers], booted: stats[:booted_workers], phase: stats[:phase] } : { mode: "single" }
+    up = odoshi_up_state(launcher)
+    meta[:up] = (up == :up) unless up == :unprobeable
+    meta
   rescue StandardError
     {}
   end
+
+  # :up | :down | :booting (no 2xx yet) | :unprobeable (no tcp bind, no override)
+  def odoshi_up_state(launcher)
+    url = odoshi_health_url(launcher)
+    return :unprobeable unless url
+    if Odoshi::Probe.http?(url)
+      @odoshi_up_once = true
+      :up
+    else
+      @odoshi_up_once ? :down : :booting
+    end
+  end
+
+  def odoshi_health_url(launcher)
+    return @odoshi_health_url if defined?(@odoshi_health_url)
+    @odoshi_health_url =
+      if (override = ENV["ODOSHI_HEALTH_URL"]) && !override.empty?
+        override
+      elsif (bind = Array(launcher.options[:binds]).find { |b| b.start_with?("tcp://") })
+        # tcp://host:port — probe loopback on the bound port ("0.0.0.0" isn't a
+        # connectable address)
+        port = bind.split(":").last.to_i
+        "http://127.0.0.1:#{port}#{HEALTH_PATH}"
+      end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: odoshi
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - timimsms