standard_health 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b9de071226844b0a4c1304b7b81d21ba11b963e3c4ad082aebd05a82a24fa92
-  data.tar.gz: dd4bab92dade63959f66db19ee8467c753e39a1f77dd12706adff721460bc14e
+  metadata.gz: 3cf58624de0179c4903a4159e227baa82079b2a78e97679122a429b186783918
+  data.tar.gz: 33963ed5e02ec9794a3133e4fbf3444cb443bc821045ec8bde6ecfb4b575f0a0
 SHA512:
-  metadata.gz: 1b6431be6025cdfb36f4059d1d295464c43d0daf927155cd53953c34cbac683ce04fbd810acc7217765be574fa4ea85eb59a8186d9326c617225705efdf878ef
-  data.tar.gz: 623ea6e63b5f4e11c281ad64d08e60ec10e858b960adcc6758ffa98970cc5e92cd4c0e64406d679aad2d44e387800de88f2bef521f5513899188ae81e811cba9
+  metadata.gz: 846b8334841aeb56c429f8a767f76c1e3e22e849da7f5de261370895cb3d7e735e2ee1fe3a72508637474f0338b34c05848bdda32e359bee783857ca3dd85e79
+  data.tar.gz: b6fefd789b745ec5a20819c46b89d610b226283b09024db1426ba5aacebee6838941f9d9c423b152bc55df2ab09bd341906cc5b15de6e2a7c0c59a5891d291f6

data/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-22
+
+### Changed
+
+- **Re-registering a check replaces it.** `register_check` and
+  `register_aggregate_check` replace an existing registration of the same name
+  in place (last writer wins) instead of appending a second one, matching
+  `register_diagnostics_assertion`. A `configure` block that runs twice, e.g.
+  from `to_prepare` on reload, no longer runs every check twice.
+- **`env_spec` aliases are checked at boot.** Assigning `c.env_spec = …` calls
+  the new `EnvSpec#validate!`, which raises `EnvSpec::UnknownModeAlias` naming
+  every `in:` alias that has no `mode_alias`. Before, an undeclared alias raised
+  only on the first audit, which was a production `/diagnostics/env` request
+  (it 500'd one app's doctor tier once). All five estate apps declare every
+  alias they use, so none of them is affected.
+
+## [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
@@ -362,7 +362,7 @@ end
 
 - `nil` (omitted) — entry always applies
 - `Array<String>` — literal mode list (existing behaviour)
-- `Symbol` — resolved against `mode_alias` at audit time. An undeclared Symbol raises `StandardHealth::EnvSpec::UnknownModeAlias`.
+- `Symbol` — resolved against `mode_alias`. Assigning the spec (`c.env_spec = …`) checks every alias, so an undeclared Symbol raises `StandardHealth::EnvSpec::UnknownModeAlias` at boot, naming each unknown alias, rather than on the first `/diagnostics/env` request.
 
 ### `description:` and `consumed_by:`
 
@@ -522,6 +522,10 @@ end
 
 `with_timing` captures `latency_ms` on success and converts any `StandardError` into `{ status: :fail, error: <message> }`.
 
+Registering a name that is already registered replaces that check in place (the
+same for `register_aggregate_check`), so a `configure` block that runs twice,
+e.g. from `to_prepare` on reload, doesn't run any check twice.
+
 **Per-registration options (0.6.0).** Keywords other than `critical:` and
 `timeout:` are forwarded to the check's constructor, and validated against its
 signature at registration — a typo fails at boot, not on every probe:
@@ -806,9 +810,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 +954,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

@@ -86,7 +86,16 @@ module StandardHealth
     # An optional `StandardHealth::EnvSpec` instance describing required and
     # recommended environment variables for the host app. Audited via the
     # /diagnostics/env endpoint.
-    attr_accessor :env_spec
+    attr_reader :env_spec
+
+    # Validates the spec as it is assigned (`EnvSpec#validate!`), so an
+    # `in:` alias with no `mode_alias` fails the initializer at boot rather
+    # than raising on the first audit, which is a /diagnostics/env request
+    # in production.
+    def env_spec=(spec)
+      spec.validate! if spec.respond_to?(:validate!)
+      @env_spec = spec
+    end
 
     # --- Instrumentation -----------------------------------------------
     #
@@ -192,7 +201,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.
@@ -268,13 +279,16 @@ module StandardHealth
     #   Validated against the constructor's signature HERE, so a typo fails
     #   at boot instead of turning into an ArgumentError on every probe (which
     #   the aggregator would dutifully report as a failing check forever).
+    #
+    # Re-registering a name replaces that registration in place (last writer
+    # wins), so `configure` can safely re-run, e.g. from `to_prepare` on
+    # reload, without running the check twice.
     def register_check(name, klass, critical: false, timeout: nil, **options)
       validate_check_options!(klass, options)
       registration = Registration.new(
         name: name.to_sym, klass: klass, critical: critical, timeout: timeout, options: options
       )
-      @checks << registration
-      registration
+      upsert_registration(@checks, registration)
     end
 
     # The check set every consumer app registers by hand. Each entry: default
@@ -360,13 +374,14 @@ module StandardHealth
     #
     #   c.register_aggregate_check :solid_cable, StandardHealth::Checks::SolidCable
     #   c.register_aggregate_check :attestation_roots, "AttestationRootsCheck"
+    #
+    # Re-registering a name replaces it in place, as for #register_check.
     def register_aggregate_check(name, klass, critical: false, timeout: nil, **options)
       validate_check_options!(klass, options)
       registration = Registration.new(
         name: name.to_sym, klass: klass, critical: critical, timeout: timeout, options: options
       )
-      @aggregate_checks << registration
-      registration
+      upsert_registration(@aggregate_checks, registration)
     end
 
     DiagnosticsAssertion = Struct.new(:name, :callable)
@@ -438,6 +453,13 @@ module StandardHealth
 
     private
 
+    # Replaces the registration with the same name in place, or appends.
+    def upsert_registration(registry, registration)
+      index = registry.index { |existing| existing.name == registration.name }
+      index ? registry[index] = registration : registry << registration
+      registration
+    end
+
     # Rejects option keys the check's constructor cannot accept. Only
     # inspects the signature — never instantiates — so a check with side
     # effects in `initialize` is not run at boot. A constructor taking

data/lib/standard_health/env_spec.rb

@@ -115,6 +115,21 @@ module StandardHealth
       @mode_aliases[name.to_sym] = Array(modes).map(&:to_s)
     end
 
+    # Resolves every `in:` alias now. `Configuration#env_spec=` calls this,
+    # so an undeclared or misspelt alias fails at boot instead of raising on
+    # the first audit (a /diagnostics/env request, or an EnvSpecAudit row).
+    #
+    # @raise [UnknownModeAlias] naming every unknown alias
+    # @return [self]
+    def validate!
+      unknown = entries.filter_map { |entry| entry.modes if alias_unknown?(entry.modes) }.uniq
+      return self if unknown.empty?
+
+      raise UnknownModeAlias,
+        "Unknown mode alias#{"es" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")} " \
+        "(declare it with mode_alias)"
+    end
+
     # Group subsequent declarations under a label. Pure metadata —
     # propagated to audit rows as `group:` and otherwise inert. Nested
     # `group` blocks are supported; the innermost label is the one that
@@ -253,6 +268,10 @@ module StandardHealth
       modes.include?(mode_str)
     end
 
+    def alias_unknown?(modes)
+      modes.is_a?(Symbol) && !@mode_aliases.key?(modes)
+    end
+
     def resolve_modes(modes)
       return nil if modes.nil?
       if modes.is_a?(Symbol)

data/lib/standard_health/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_health
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 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: []