standard_health 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5845fe7433611028fb103afb457683b22717a8f1aa79848f425a2cd5d7c9bd7a
-  data.tar.gz: c83d29991ba9b19b2ce234e5ef3cacabf198af323b97809927ef36608c49ba7e
+  metadata.gz: 4b9de071226844b0a4c1304b7b81d21ba11b963e3c4ad082aebd05a82a24fa92
+  data.tar.gz: dd4bab92dade63959f66db19ee8467c753e39a1f77dd12706adff721460bc14e
 SHA512:
-  metadata.gz: eddef6b2df86d0ff116a63793b009f3b3afe81ed3f437fcd5f1fea15be0545ca2a384ea346bae3c12050ffc8f95183af4ee5414a8739ead14910b2bcd0a45ea5
-  data.tar.gz: cb15f56c75ec0464412c16360d788b8f714d73c844a3e7bde8564295e56d2e56bdc63bb9c5987792efd65c8c3158e4e9b0edde991f0ea69e0a8dfecf93c9361f
+  metadata.gz: 1b6431be6025cdfb36f4059d1d295464c43d0daf927155cd53953c34cbac683ce04fbd810acc7217765be574fa4ea85eb59a8186d9326c617225705efdf878ef
+  data.tar.gz: 623ea6e63b5f4e11c281ad64d08e60ec10e858b960adcc6758ffa98970cc5e92cd4c0e64406d679aad2d44e387800de88f2bef521f5513899188ae81e811cba9

data/CHANGELOG.md

@@ -7,6 +7,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-24
+
+The Phase 4 release. 0.6 deprecated nothing, so nothing is removed. It adds
+the one extension point the app adoptions still needed their own controller
+for. The response of `/diagnostics/env` gains a key, and a failing assertion
+changes its `status`, so this ships as a minor.
+
+### Added
+
+- **`Configuration#register_diagnostics_assertion(name, callable = nil, &block)`**
+  adds a runtime assertion to the doctor tier. `/diagnostics/env` now renders
+  `assertions: [...]` next to `audit`. The key is always present (`[]` when
+  none are registered). Each callable returns a Hash with `status:` (`:ok` /
+  `:warn` / `:error`) plus detail keys, and the gem sets `name:`. A raise
+  becomes an `:error` row with `error_class` / `error` and is reported to
+  `Rails.error` as handled (`context: { diagnostics_assertion: name }`,
+  `source: "standard_health"`). A non-Hash result or an unknown status also
+  becomes an `:error` row. Re-registering a name replaces it (reload-safe).
+  `diagnostics_assertions` / `reset_diagnostics_assertions!` are provided.
+  Assertions never run on `/alive`, `/ready` or the aggregate tier, and stay
+  behind `diagnostics_basic_auth`.
+- **`StandardHealth::DiagnosticsAssertions.run` / `.failing?`**, public for
+  hosts that render their own diagnostics endpoint.
+
+### Changed
+
+- **`/diagnostics/env` `status` also rolls up assertions.** An `:error`
+  assertion makes it `incomplete` (`:warn` does not). The HTTP status is still
+  200. Nothing changes unless you register an assertion.
+- **`StandardHealth::DiagnosticsAuthentication` is public, semver-stable
+  API.** Including it into a host controller (as sidekick-web does) is now a
+  supported extension point: the include, its single `before_action`, and the
+  401 challenge / 403 fail-closed refusal. Its private method names are not
+  part of the contract.
+
+### Upgrade notes (0.6.x → 0.7.0)
+
+Grepped `origin/main` of sidekick-web, jumpdrive-web, fundbright-web,
+luminality-web and nutripod-web on 2026-09-24.
+
+- **No required host change.** Nothing was removed.
+- **Monitors or scripts that parse `/diagnostics/env`:** a new `assertions`
+  key appears, and `status` can become `incomplete` from an `:error`
+  assertion once you register one.
+- **sidekick-web (optional, recommended):** move the three assertions in
+  `app/controllers/health_diagnostics_controller.rb` (`statement_timeout`,
+  `rate_limit_store`, `attestation_roots`) into
+  `register_diagnostics_assertion` calls in
+  `config/initializers/standard_health.rb`. Then delete the controller and its
+  `config/routes.rb` route that shadows the engine's `/health/diagnostics/env`.
+  Keep each assertion's Hash shape. Drop the per-assertion
+  `rescue => e; { status: :error, error: e.message }`, which the gem now
+  provides (it also adds `error_class`). The response gains `status`, which
+  the host controller never rendered.
+- Other apps have no diagnostics controller of their own. Nothing to do.
+
+### Documentation
+
+- Aggregate-tier check **timeouts** are deliberately not sent to `Rails.error` (true since 0.6.1). A timeout is the gem's own budget firing on a slow dependency, already emitted as `standard_health.check.timed_out`, and the pre-0.6 host controllers had no per-check timeouts. A code comment and a spec now pin this.
+
+## [0.6.1] - 2026-09-24
+
+### Fixed
+
+- **A check that raises on the aggregate tier is reported to `Rails.error` again.** Before 0.6.0 every host's aggregate controller rescued a raising check and called `Rails.error.report(e, handled: true, ...)`. When the engine took over the tier, the exception was only logged by the Logger notifier, so a buggy aggregate check stopped reaching Sentry (noted in the jumpdrive-web and sidekick-web adoptions). The Aggregator now reports it as handled with context `{ health_check: <name>, tier: "aggregate" }`. Severity follows the readiness Sentry notifier: `:error` for a critical check, `:warning` otherwise. The readiness tier is unchanged. Its failures still reach Sentry through the transition-gated `ready.evaluated` notifier, which keeps a ~6/min probe from flooding the tracker. Checks that return a `:fail` row (every built-in check) are not reported. The report is rescued, so a broken error subscriber cannot 500 the tier.
+
+### Documentation
+
+- The aggregate tier re-runs the `register_check` readiness checks by default (`aggregate_readiness_checks = true`), so a failing critical check (database, Solid Queue) makes `/health` answer **503 `unavailable`**, not only `/ready`.
+- The aggregate body reports `"unavailable"`, never StandardCircuit's `"critical"`. Monitors matching on `"critical"` need updating (as noted in 0.6.0's migration notes).
+- `StandardHealth::DiagnosticsAuthentication` is the request-time gate behind `diagnostics_basic_auth`. The README now notes that a host can include it into its own diagnostics controller, as sidekick-web does. It is not yet a documented, semver-stable extension point.
+
 ## [0.6.0] - 2026-09-24
 
 DX release: absorbs the code every consumer app copy-pasted around the engine.

data/README.md

@@ -109,14 +109,31 @@ end
 | `degraded` | 200 | a non-critical check failed or was skipped, or the circuit roll-up is `:degraded` |
 | `ok` | 200 | otherwise |
 
+**The aggregate tier re-runs your readiness checks by default.** With
+`aggregate_readiness_checks` on (the default), every `register_check`
+registration runs here as well as on `/ready`. A failing critical check, such
+as `:database` or `:solid_queue` from `register_default_checks`, therefore turns
+`/health` into a **503 `unavailable`**, not just `/ready`. Point an uptime
+monitor at `/health` and a database outage pages as a 503. If your aggregate
+tier should only report soft signals (sidekick), set
+`aggregate_readiness_checks = false`.
+
 StandardCircuit's own word `critical` is translated to `unavailable`, so both
-tiers speak one vocabulary. `circuits` is omitted when StandardCircuit isn't
+tiers speak one vocabulary. The aggregate body never says `"critical"`. `circuits` is omitted when StandardCircuit isn't
 loaded (or `aggregate_circuits = false`); if `health_report` raises (circuit
 store down) the tier degrades and reports `circuits_error: { error_class,
 error_code }` instead of 500ing. Check rows are redacted exactly like `/ready`,
 with the same `detail_token` break-glass. `register_aggregate_check` checks
 run **only** here — never on `/ready` — and default to `critical: false`.
 
+A check that **raises** on this tier, rather than returning a `:fail` row, is
+also reported to `Rails.error` as handled (since 0.6.1), with context
+`{ health_check:, tier: "aggregate" }` and severity `:error` for a critical
+check or `:warning` otherwise. That matches what the pre-0.6 host controllers
+did. Per-check timeouts are not reported; they surface as
+`standard_health.check.timed_out`. `/ready` does not do this: its failures reach Sentry through the
+transition-gated `ready.evaluated` notifier.
+
 With `aggregate_endpoint` off (the default) the engine's root route carries a
 per-request constraint that never matches, so a bare `/health` cascades to your
 own route exactly as before. Once on, the engine answers `/health` regardless
@@ -402,11 +419,13 @@ Since 0.4.1 the response carries a `status` alongside the audit, so a caller
 can gate on one field instead of re-implementing the roll-up:
 
 ```json
-{ "mode": "production", "status": "incomplete", "audit": [ ... ] }
+{ "mode": "production", "status": "incomplete", "audit": [ ... ], "assertions": [ ... ] }
 ```
 
 `incomplete` means at least one row is a **violation** — `missing`,
-`forbidden`, or `mismatch`. `should_set` is advisory and never affects it.
+`forbidden`, or `mismatch` — or (since 0.7.0) a registered diagnostics
+assertion reported `error`. `should_set` and an assertion's `warn` are
+advisory and never affect it.
 
 The level is deliberately not consulted for `mismatch`: a `recommended` var
 declared with an `expected_value:` that does not hold is a failed assertion,
@@ -417,6 +436,56 @@ not advice.
 free — which is why they joined this roll-up rather than getting a verdict of
 their own.
 
+### Runtime assertions: `register_diagnostics_assertion` (0.7.0)
+
+Env presence can't prove that a setting took effect. For example, the live
+`statement_timeout` may still be `0`, a rate limiter may have fallen back to
+Solid Cache, or a pinned certificate may be about to expire. Register those
+checks as assertions and the engine renders them on `/diagnostics/env` under
+`assertions:`, behind the same `diagnostics_basic_auth` gate:
+
+```ruby
+StandardHealth.configure do |c|
+  c.register_diagnostics_assertion(:statement_timeout) do
+    value = ActiveRecord::Base.connection.select_value("SHOW statement_timeout").to_s
+    { status: value.strip == "0" ? :warn : :ok, value: value, expected: "non-zero" }
+  end
+
+  # Any callable works; reference app constants inside it, not at boot.
+  c.register_diagnostics_assertion(:rate_limit_store, -> { RateLimitAssertion.call })
+end
+```
+
+```json
+{ "mode": "production", "status": "ok", "audit": [ ... ],
+  "assertions": [ { "name": "statement_timeout", "status": "ok", "value": "15s", "expected": "non-zero" } ] }
+```
+
+- The callable takes no arguments and returns a Hash with `status:` set to
+  `:ok`, `:warn` or `:error`. Other keys are rendered as-is. The gem sets
+  `name:`, and the callable can't override it.
+- An assertion that raises becomes `{ status: "error", error_class:, error: }`
+  and is reported to `Rails.error` as handled. The tier is authenticated, so
+  the message is shown. A non-Hash result or an unknown status also becomes an
+  `:error` row. One broken assertion never takes the endpoint down.
+- An `:error` row makes the top-level `status` `incomplete`. `:warn` does not.
+  The endpoint still returns 200.
+- Assertions run per request, and only on this tier, never on `/alive`,
+  `/ready` or the aggregate. They have no timeout, so keep them cheap.
+- Re-registering a name replaces it, so it is safe inside `to_prepare`.
+  `reset_diagnostics_assertions!` clears them in specs.
+- A host that keeps its own diagnostics controller can render
+  `StandardHealth::DiagnosticsAssertions.run` itself.
+
+**Replace your host code with it.** sidekick-web's
+`app/controllers/health_diagnostics_controller.rb` exists to add three
+assertions (`statement_timeout`, `rate_limit_store`, `attestation_roots`) to
+the env audit. Move each into a `register_diagnostics_assertion`, delete the
+controller, and delete its route
+(`get "/health/diagnostics/env", to: "health_diagnostics#env"` ahead of the
+engine mount). Its `rescue => e; { status: :error, error: e.message }`
+wrappers go too, because the gem does that now.
+
 ### Surfacing the audit on a health tier
 
 `/diagnostics/env` is authed and polled by nobody, so config drift declared in
@@ -590,6 +659,17 @@ c.diagnostics_basic_auth = {
   nothing.
 - Off by default; independent of `diagnostics_parent_controller` (if you set
   both, the parent's callbacks run first).
+- The request-time gate is the `StandardHealth::DiagnosticsAuthentication`
+  concern, which the engine includes into its own `DiagnosticsController`.
+  **Since 0.7.0 it is public, semver-stable API:** `include
+  StandardHealth::DiagnosticsAuthentication` into any `ActionController::API`
+  or `::Base` controller to put a host endpoint behind the same fail-closed
+  gate. The contract is the include, the one `before_action` it installs, and
+  the 401 challenge / 403 refusal behaviour. Its private method names are not
+  part of it. It is a no-op until `diagnostics_basic_auth` is set. If your
+  controller only exists to add runtime assertions, use
+  [`register_diagnostics_assertion`](#runtime-assertions-register_diagnostics_assertion-070)
+  instead and delete the controller.
 
 **Replace your host code with it.** Delete
 `app/controllers/standard_health_host_controller.rb` and the

data/app/controllers/concerns/standard_health/diagnostics_authentication.rb

@@ -7,6 +7,15 @@ module StandardHealth
   # `DiagnosticsController` only — never `HealthController` — so /alive and
   # /ready stay anonymous for orchestrator probes.
   #
+  # PUBLIC API (since 0.7.0, semver-stable): a host that serves its own
+  # diagnostics endpoint can `include StandardHealth::DiagnosticsAuthentication`
+  # into any ActionController::API or ::Base controller to put it behind the
+  # same fail-closed gate. The contract is the include, the `before_action`
+  # it installs, and the 401 challenge / 403 refusal behaviour below; the
+  # private method names are not part of it. Prefer
+  # `register_diagnostics_assertion` when all the host controller adds is
+  # assertions.
+  #
   # A NO-OP when `diagnostics_basic_auth` is unset, so hosts that gate
   # diagnostics through `diagnostics_parent_controller` see no change. Both
   # can be used together; the parent's callbacks run first.

data/app/controllers/standard_health/diagnostics_controller.rb

@@ -27,11 +27,13 @@ module StandardHealth
       root = defined?(Rails) ? Rails.root : nil
 
       audit = spec ? spec.audit(ENV.to_h, mode: mode, root: root) : []
+      assertions = DiagnosticsAssertions.run
 
       render json: {
         mode: mode,
-        status: audit_status(audit),
+        status: audit_status(audit, assertions),
         audit: audit,
+        assertions: assertions,
         generated_at: Time.now.utc.iso8601
       }
     end
@@ -53,13 +55,16 @@ module StandardHealth
     # advice. The advisory status stays `:should_set`, which is not a
     # violation.
     #
+    # A registered diagnostics assertion (`register_diagnostics_assertion`)
+    # that reports `:error` also makes it `:incomplete`; `:warn` does not.
+    #
     # The endpoint still returns 200 either way, so nothing that asserts on
     # the status code breaks.
-    def audit_status(audit)
+    def audit_status(audit, assertions = [])
       violated = Array(audit).any? do |row|
         EnvSpec::VIOLATION_STATUSES.include?(row[:status])
       end
-      violated ? :incomplete : :ok
+      (violated || DiagnosticsAssertions.failing?(assertions)) ? :incomplete : :ok
     end
   end
 end

data/lib/standard_health/aggregator.rb

@@ -111,6 +111,12 @@ module StandardHealth
       emit_check(row, tier)
       row
     rescue CheckTimeout
+      # Deliberately NOT sent to Rails.error (unlike the StandardError branch
+      # below). A timeout is our own budget firing on a slow dependency, not a
+      # bug in the check: it is already visible as `check.timed_out` and as a
+      # failing row, and reporting it per poll would page on latency. The
+      # pre-0.6 host aggregate controllers had no per-check timeouts, so
+      # nothing reported there is lost.
       emit("standard_health.check.timed_out",
            name: reg.name, critical: reg.critical, timeout_s: timeout, **tier_attrs(tier))
       row = {
@@ -131,10 +137,38 @@ module StandardHealth
         error_class: e.class.name
       }
       emit_check(row, tier)
+      report_raised_check(e, reg, tier)
       row
     end
     private_class_method :safe_run
 
+    # A check that RAISES (rather than returning a :fail row) on a
+    # non-readiness tier goes to `Rails.error` as handled. Before 0.6.0 every
+    # host's aggregate controller did exactly this; moving the tier into the
+    # engine left the exception only in the Logger notifier's line, so a buggy
+    # aggregate check stopped reaching the error tracker.
+    #
+    # Readiness is deliberately excluded: its failures already reach Sentry
+    # through the transition-gated `ready.evaluated` notifier, and reporting
+    # every raise from a ~6/min/instance probe would be exactly the noise that
+    # notifier exists to prevent. Severity mirrors that notifier: a critical
+    # check is an :error (it makes the tier :unavailable), otherwise :warning.
+    def self.report_raised_check(error, reg, tier)
+      return if tier == :ready
+      return unless defined?(::Rails) && ::Rails.respond_to?(:error) && ::Rails.error
+
+      ::Rails.error.report(
+        error,
+        handled: true,
+        severity: reg.critical ? :error : :warning,
+        context: { health_check: reg.name.to_s, tier: tier.to_s }
+      )
+    rescue StandardError
+      # Never-raise: a broken error subscriber must not 500 the tier.
+      nil
+    end
+    private_class_method :report_raised_check
+
     def self.budget_exhausted?(budget, started)
       return false unless budget
 

data/lib/standard_health/configuration.rb

@@ -220,6 +220,7 @@ module StandardHealth
       @env_spec = nil
       @checks = []
       @aggregate_checks = []
+      @diagnostics_assertions = []
       @aggregate_endpoint = false
       @aggregate_readiness_checks = true
       @aggregate_circuits = true
@@ -368,6 +369,51 @@ module StandardHealth
       registration
     end
 
+    DiagnosticsAssertion = Struct.new(:name, :callable)
+
+    # Adds a runtime assertion to the doctor tier (`GET /diagnostics/env`),
+    # rendered under `assertions:` next to the env audit. For facts env
+    # presence can't prove: the live `statement_timeout`, the cache store a
+    # rate limiter actually resolved to, a pinned root's expiry. Replaces a
+    # host diagnostics controller that exists only to add these.
+    #
+    #   c.register_diagnostics_assertion(:statement_timeout) do
+    #     value = ActiveRecord::Base.connection.select_value("SHOW statement_timeout").to_s
+    #     { status: value == "0" ? :warn : :ok, value: value, expected: "non-zero" }
+    #   end
+    #
+    # The callable takes no arguments and returns a Hash with `status:`
+    # (`:ok`, `:warn` or `:error`) plus any detail keys. `name:` is set by
+    # the gem. It runs per request, on the authenticated tier only, never on
+    # /alive, /ready or the aggregate. A raise, a non-Hash, or an unknown
+    # status becomes an `:error` row (a raise is also reported to
+    # `Rails.error` as handled). An `:error` row makes the endpoint's
+    # `status` `incomplete`; `:warn` does not.
+    #
+    # Re-registering a name replaces it, so `configure` can safely re-run
+    # from `to_prepare` on reload.
+    def register_diagnostics_assertion(name, callable = nil, &block)
+      callable ||= block
+      unless callable.respond_to?(:call)
+        raise ArgumentError, "register_diagnostics_assertion(#{name.inspect}) needs a callable or a block"
+      end
+
+      assertion = DiagnosticsAssertion.new(name.to_sym, callable)
+      @diagnostics_assertions.reject! { |existing| existing.name == assertion.name }
+      @diagnostics_assertions << assertion
+      assertion
+    end
+
+    # @return [Array<DiagnosticsAssertion>] in registration order
+    def diagnostics_assertions
+      @diagnostics_assertions.dup
+    end
+
+    # Drop registered diagnostics assertions. Test hygiene.
+    def reset_diagnostics_assertions!
+      @diagnostics_assertions = []
+    end
+
     # @return [Array<Registration>] aggregate-only checks
     def aggregate_checks
       @aggregate_checks.dup

data/lib/standard_health/diagnostics_assertions.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module StandardHealth
+  # Runs the host's `register_diagnostics_assertion` callables for the doctor
+  # tier (`/diagnostics/env`, behind `diagnostics_basic_auth`).
+  #
+  # An assertion is a runtime fact that env presence cannot express: the live
+  # `statement_timeout`, which cache store a limiter actually resolved to, how
+  # close a pinned certificate is to expiry. Each callable returns a Hash with
+  # at least `status:` (`:ok`, `:warn` or `:error`); any other keys (`value:`,
+  # `expected:`, ...) are rendered as-is. The gem sets `name:`.
+  #
+  # Public: a host with its own diagnostics controller can render
+  # `StandardHealth::DiagnosticsAssertions.run` itself.
+  module DiagnosticsAssertions
+    STATUSES = %i[ok warn error].freeze
+
+    module_function
+
+    # @return [Array<Hash>] one row per registered assertion, in registration
+    #   order. Never raises: an assertion that raises, returns a non-Hash, or
+    #   returns an unknown status becomes an `:error` row.
+    def run(config = StandardHealth.config)
+      config.diagnostics_assertions.map { |assertion| evaluate(assertion) }
+    end
+
+    # True when any row is `:error`. `:warn` is advisory.
+    def failing?(rows)
+      Array(rows).any? { |row| row[:status] == :error }
+    end
+
+    def evaluate(assertion)
+      result = assertion.callable.call
+      return invalid(assertion.name, "returned #{result.class}, expected a Hash") unless result.is_a?(Hash)
+
+      row = result.to_h.transform_keys(&:to_sym)
+      status = row[:status].respond_to?(:to_sym) ? row[:status].to_sym : nil
+      return invalid(assertion.name, "returned status #{row[:status].inspect}, expected one of #{STATUSES.inspect}") unless STATUSES.include?(status)
+
+      { name: assertion.name }.merge(row.except(:name)).merge(status: status)
+    rescue StandardError => e
+      report(e, assertion.name)
+      # The doctor tier is authenticated, so the message is shown (the /ready
+      # redaction rationale does not apply); the class is kept separately
+      # for grouping.
+      { name: assertion.name, status: :error, error_class: e.class.name, error: e.message }
+    end
+
+    def invalid(name, detail)
+      { name: name, status: :error, error: "diagnostics assertion #{name} #{detail}" }
+    end
+
+    def report(error, name)
+      return unless defined?(::Rails) && ::Rails.respond_to?(:error) && ::Rails.error
+
+      ::Rails.error.report(error, handled: true, severity: :warning,
+        context: { diagnostics_assertion: name }, source: "standard_health")
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/standard_health/version.rb

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

data/lib/standard_health.rb

@@ -22,6 +22,7 @@ require "standard_health/subscribers"
 require "standard_health/redactor"
 require "standard_health/aggregator"
 require "standard_health/aggregate_report"
+require "standard_health/diagnostics_assertions"
 
 module StandardHealth
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_health
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -54,6 +54,7 @@ files:
 - lib/standard_health/checks/solid_cache.rb
 - lib/standard_health/checks/solid_queue.rb
 - lib/standard_health/configuration.rb
+- lib/standard_health/diagnostics_assertions.rb
 - lib/standard_health/diagnostics_basic_auth.rb
 - lib/standard_health/engine.rb
 - lib/standard_health/env_spec.rb