standard_health 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b9de071226844b0a4c1304b7b81d21ba11b963e3c4ad082aebd05a82a24fa92
-  data.tar.gz: dd4bab92dade63959f66db19ee8467c753e39a1f77dd12706adff721460bc14e
+  metadata.gz: 162374f071e6634d43876ef75f8fa6f50b1ec7bfd6a8d01bd94a91c854151d09
+  data.tar.gz: 58c40844359768a3d905c75575599dc1bf61dab15ebabc372c3e5e56cd4e169d
 SHA512:
-  metadata.gz: 1b6431be6025cdfb36f4059d1d295464c43d0daf927155cd53953c34cbac683ce04fbd810acc7217765be574fa4ea85eb59a8186d9326c617225705efdf878ef
-  data.tar.gz: 623ea6e63b5f4e11c281ad64d08e60ec10e858b960adcc6758ffa98970cc5e92cd4c0e64406d679aad2d44e387800de88f2bef521f5513899188ae81e811cba9
+  metadata.gz: a93890d618342991d02699f9a68d0cf432596f4fba5eff7659d4d4c8675d22e5e0bac3d996abed41e02ddd7f53b84c771f21e093a6c6e22b39404ec9ccc7498c
+  data.tar.gz: 13b347704251b47c6a877ce5fb559686d9fee639610109300da1fd989627010a3823f678ab420330a26ac851548647da3ab12405081cd13a2d9024c90d4bb5dc

data/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-09-25
+
+### Fixed
+
+- **Skipped checks no longer degrade the aggregate.** A check that returns
+  `status: :skipped` itself means "not applicable here" (the feature it
+  covers is not configured or not enforced). It is now **neutral** in the
+  roll-up on every tier (`/ready` and the aggregate `/health`): it neither
+  degrades nor fails the status. Before, it counted like a failing
+  non-critical check, which held sidekick-web's `/health` at `degraded`
+  permanently while attestation was unconfigured. The row still renders in
+  `checks[]` with `"status": "skipped"`, and `check.completed` still fires,
+  so it stays visible. It is no longer listed in the `failed[]` / `failures`
+  of `ready.evaluated` / `aggregate.evaluated`, so the Logger and Sentry
+  notifiers don't name it as failing when something else degrades.
+- **A critical check that reports `:skipped` is neutral too**, on purpose.
+  "Not applicable" says nothing about whether the instance can serve, so it
+  must not pull it out of rotation. Return `:fail` for a state that should
+  page.
+- Real failures roll up exactly as before: a failing critical check is
+  `unavailable` (503), a failing non-critical one `degraded`, including
+  alongside a skipped check.
+- **Budget skips are unchanged.** A check the `total_check_budget` never
+  reached was not performed, which is not the same as healthy. It still
+  floors the roll-up at `degraded` (never `unavailable`) and is still listed
+  in `failed[]`. Its row now carries `budget_exhausted: true`, which is how
+  the gem tells the two kinds of skip apart.
+- `/diagnostics/env` is unaffected. Its roll-up is over env-audit rows and
+  assertions (`:ok` / `:warn` / `:error`), which have no skipped state.
+
+### Changed
+
+- **Requires Rails 8.1** (`rails >= 8.1`, was `>= 8.0`). Every consumer app
+  runs 8.1; 8.0 was never exercised in CI. Ruby 3.4 remains supported.
+
+### Upgrade notes (0.7.0 → 0.7.1)
+
+- **No required host change.** An app whose aggregate was `degraded` only
+  because of a self-reported skip now reports `ok`. Monitors or smoke tests
+  that expect `degraded` in that state need updating (sidekick-web).
+
 ## [0.7.0] - 2026-09-24
 
 The Phase 4 release. 0.6 deprecated nothing, so nothing is removed. It adds

data/README.md

@@ -106,7 +106,7 @@ end
 | Status | HTTP | When |
 |---|---|---|
 | `unavailable` | 503 | a critical check failed, or a `:critical` circuit is red |
-| `degraded` | 200 | a non-critical check failed or was skipped, or the circuit roll-up is `:degraded` |
+| `degraded` | 200 | a non-critical check failed, a check was skipped by the total budget, or the circuit roll-up is `:degraded` |
 | `ok` | 200 | otherwise |
 
 **The aggregate tier re-runs your readiness checks by default.** With
@@ -806,9 +806,25 @@ go in `extra:`.
 
 The orchestrator should pull the instance out of rotation only on 503; degraded means "still serving, page someone."
 
-`skipped` also exists, for a check the total budget never reached (see
-Timeouts). A skip floors the roll-up at `degraded` and **never** produces
-`unavailable`, even for a critical check.
+`skipped` also exists, in two flavours that roll up differently:
+
+- **A check that returns `status: :skipped` itself** — "not applicable here"
+  (the feature it covers isn't configured or enforced). This is **neutral**
+  (since 0.7.1): it neither degrades nor fails the roll-up, whether the check
+  is critical or not, and it is left out of the evaluation events' `failed[]`.
+  It still renders in `checks[]` with `"status": "skipped"` and still emits
+  `check.completed`, so it stays visible. A critical check is neutral too on
+  purpose: "not applicable" says nothing about whether the instance can serve,
+  so it must not pull it out of rotation — and it must not mark it healthy
+  *because of* that check either; it simply doesn't count. If the state should
+  page, return `:fail`.
+- **A check the total budget never reached** (see Timeouts) — rendered with
+  `"budget_exhausted": true`. That check was not performed, which is not the
+  same as healthy, so it floors the roll-up at `degraded` and **never**
+  produces `unavailable`, even for a critical check.
+
+A real failure still rolls up exactly as before alongside any skip: a failing
+critical check is `unavailable`, a failing non-critical one `degraded`.
 
 ## Failure detail is redacted
 
@@ -934,8 +950,8 @@ slow-but-fine starts reporting `:fail`, and for a critical check that pulls
 the instance out of rotation. Pick values from observed `latency_ms` rather
 than intuition; that is what the `check.completed` events are for.
 
-Checks the total budget never reaches report `:skipped`, never silently `:ok`.
-A skip alone floors the roll-up at `degraded` — otherwise a slow *non-critical*
+Checks the total budget never reaches report `:skipped` (with
+`budget_exhausted: true`), never silently `:ok`. A budget skip alone floors the roll-up at `degraded` — otherwise a slow *non-critical*
 check could exhaust the budget, leave the database check unrun, and pull a
 healthy instance out of rotation.
 

data/lib/standard_health/aggregate_report.rb

@@ -18,8 +18,10 @@ module StandardHealth
   #
   # Status roll-up, in the estate's readiness vocabulary:
   #   :unavailable (503) — a critical check failed, or a :critical circuit is RED
-  #   :degraded    (200) — a non-critical check failed / was skipped, or the
-  #                        circuit roll-up is :degraded
+  #   :degraded    (200) — a non-critical check failed, a check was skipped
+  #                        by the total budget, or the circuit roll-up is
+  #                        :degraded. A check that reports :skipped itself
+  #                        (not applicable) is neutral — see Aggregator.
   #   :ok          (200) — otherwise
   #
   # StandardCircuit's own word for its worst state is `:critical`; it is
@@ -92,7 +94,7 @@ module StandardHealth
     # notifier logs this one (so redacted messages still reach logs); Sentry
     # and Metrics ignore it.
     def emit_evaluation(report, rows, circuits, started)
-      failing = rows.reject { |r| r[:status] == :ok }
+      failing = Aggregator.failing_rows(rows)
       payload = {
         status: report[:status],
         duration_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round,

data/lib/standard_health/aggregator.rb

@@ -14,11 +14,23 @@ module StandardHealth
   # Runs all registered checks and rolls them up into a single status.
   #
   # Status semantics:
-  #   :ok           — every check returned :ok
+  #   :ok           — every check returned :ok, or reported :skipped itself
   #   :degraded     — at least one non-critical check failed, OR a check was
   #                   skipped because the total budget ran out
   #   :unavailable  — at least one critical check failed
   #
+  # Two kinds of :skipped row exist, and they roll up differently (0.7.1):
+  #
+  #   * A check that RETURNS `status: :skipped` is saying "not applicable
+  #     here" (the feature it covers is not configured or not enforced). That
+  #     is NEUTRAL — it neither degrades nor fails the tier, whatever its
+  #     `critical:` flag, and it is not listed in an evaluation event's
+  #     `failed[]`. The row still renders with status "skipped", and
+  #     `check.completed` still fires, so it stays visible.
+  #   * A check the total budget never REACHED (`budget_exhausted: true` on
+  #     the row) was not performed at all, and an unperformed check is not a
+  #     healthy one. It floors the tier at :degraded — never :unavailable.
+  #
   # The aggregator never raises. Each check is invoked through `safe_run`
   # which catches `StandardError` so a buggy custom check cannot take down
   # /ready. Instrumentation is held to the same bar — every emit is wrapped
@@ -55,7 +67,7 @@ module StandardHealth
       duration_ms = ((monotonic - started) * 1000).round
       status = overall_status(check_rows)
 
-      failing = check_rows.reject { |r| r[:status] == :ok }
+      failing = failing_rows(check_rows)
 
       return { status: status, checks: check_rows, generated_at: now.iso8601 } unless tier == :ready
 
@@ -81,6 +93,21 @@ module StandardHealth
       }
     end
 
+    # The rows an evaluation event reports as failing: everything that is not
+    # :ok, except a check that reported :skipped itself (not applicable, so
+    # not a failure). A budget skip IS listed — it is the only place a skip
+    # shows up in the transition-gated event. @api private (also used by
+    # AggregateReport).
+    def self.failing_rows(rows)
+      rows.reject { |r| r[:status] == :ok || neutral_skip?(r) }
+    end
+
+    # A row the check itself reported as :skipped — "not applicable here".
+    # Neutral in the roll-up. A budget skip is not neutral. @api private
+    def self.neutral_skip?(row)
+      row[:status] == :skipped && !row[:budget_exhausted]
+    end
+
     # Per-failure detail for an evaluation event. Public (but @api private) so
     # the aggregate tier's evaluation event carries the same shape.
     # @api private
@@ -177,12 +204,15 @@ module StandardHealth
     private_class_method :budget_exhausted?
 
     # A check the total budget never reached. `:skipped`, never silently
-    # `:ok` — an unperformed check is not a healthy one.
+    # `:ok` — an unperformed check is not a healthy one. `budget_exhausted`
+    # is what separates it from a check that reported :skipped itself (which
+    # is neutral); see overall_status.
     def self.skipped_row(reg, budget)
       {
         name: reg.name,
         critical: reg.critical,
         status: :skipped,
+        budget_exhausted: true,
         error: "skipped — total check budget of #{budget}s exhausted"
       }
     end
@@ -191,10 +221,16 @@ module StandardHealth
     def self.overall_status(rows)
       return :ok if rows.empty?
 
-      failures = rows.reject { |r| r[:status] == :ok }
+      # A check that reported :skipped itself is not applicable here, so it is
+      # NEUTRAL: it must not degrade the tier (sidekick-web's non-critical
+      # attestation check held /health at "degraded" forever while attestation
+      # was simply not configured), and a critical one must not fail it
+      # either — "not applicable" says nothing about whether the app can
+      # serve. It stays in checks[] as "skipped" for visibility.
+      failures = failing_rows(rows)
       return :ok if failures.empty?
 
-      # A SKIP MUST NEVER PRODUCE :unavailable, even for a critical check.
+      # A BUDGET SKIP MUST NEVER PRODUCE :unavailable, even for a critical check.
       # Otherwise a slow *non-critical* check could exhaust the budget, leave
       # the database check unrun, and pull a perfectly healthy instance out of
       # rotation — a self-inflicted outage caused by the safety mechanism.

data/lib/standard_health/check.rb

@@ -11,6 +11,16 @@ module StandardHealth
   #
   #   { status: :fail, error: "connection refused" }
   #
+  # or, when the check does not apply to this deployment (the feature it
+  # covers is not configured or not enforced):
+  #
+  #   { status: :skipped }
+  #
+  # A self-reported :skipped is NEUTRAL in the roll-up (0.7.1): it never
+  # degrades or fails the tier, even for a critical check, but it still
+  # renders in `checks[]` as "skipped". Return :fail, not :skipped, for
+  # anything that should page.
+  #
   # The `with_timing` helper wraps a block, captures latency, and converts
   # any unhandled `StandardError` into a `:fail` row so subclasses don't
   # have to repeat the pattern.

data/lib/standard_health/configuration.rb

@@ -192,7 +192,9 @@ module StandardHealth
     attr_accessor :default_check_timeout
 
     # Budget across all checks, evaluated BEFORE each check starts. Checks not
-    # reached are reported :skipped, and a skip alone floors the roll-up at
+    # reached are reported :skipped with `budget_exhausted: true` (unlike a
+    # check that reports :skipped itself, which is neutral), and such a skip
+    # alone floors the roll-up at
     # :degraded — never :unavailable. Otherwise a slow NON-critical check could
     # exhaust the budget, leave a critical check unrun, and pull a healthy app
     # out of rotation. nil = no budget.

data/lib/standard_health/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StandardHealth
-  VERSION = "0.7.0"
+  VERSION = "0.7.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_health
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Jaryl Sim
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
 description: StandardHealth is a mountable Rails engine providing /alive, /ready,
   and /diagnostics/env endpoints, with a configuration block for registering custom
   checks and a DSL for declaring required and recommended environment variables.
@@ -88,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A drop-in health check and environment-spec engine for Rails 8 host apps.
 test_files: []