standard_health 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 298b48147224460e942fb5dd9440596ef128f0967dc7212a507756b9b45ae1b5
-  data.tar.gz: 5008923ddf09d5637f9e6c07b95bf9073b15d0e79b2d0e00646170478e5d7aee
+  metadata.gz: 4bc8cdc021df7485cb1443cf6902b6fee31627ad6135d9eef6f284cd5eed47e0
+  data.tar.gz: bfd4e8a50e602685430481b85a0ebf604d1e930db71ce47492036d772f4aa13c
 SHA512:
-  metadata.gz: 61f79addc2cba3dc84019036dd38b0917b5c812193b6b8af551b4efdd8578f93499a8efaed5f95b38efa07d71bf5d3bfe19495ff7f54eea145895169289aa7e5
-  data.tar.gz: ff348b35a931bed97044118e15b275ac1daed5fae93929c1f2976bc1db1947dbbeb8a05fe8029bc277311e6174e73e8be94c3afc060c880282a1fa1906406d63
+  metadata.gz: 32ec724c45eb9899e4d241d5681d296e1ac5745c3ff1852b5a187dea1fcc2a6b7ff7a922c08f925f0b59189ca8523d11fd034a5743f394186d91c4c1f2d8596d
+  data.tar.gz: 4711ceae81d4b9d0c19b440cc62fe8b2677ce569661adf741775ecc7933ee93c68402c8141ca830e76a6a75aa023c3f7759ef4d68a175d38280a2d971e83b964

data/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-29
+
+### Added
+
+- `if:` and `unless:` Proc predicates on `required` and `recommended`. Evaluated at audit time; when `unless:` returns truthy or `if:` returns falsy the entry is reported with `status: :not_applicable` and a `reason` field. Solves the MyInfo mock-mode case where `MYINFO_PRIVATE_JWKS` is only required outside mock mode.
+- `mode_alias` top-level DSL inside `EnvSpec.define`. Maps a Symbol to an `Array<String>` of `APP_ENVIRONMENT` values. `in:` now accepts a Symbol that is resolved against declared aliases at audit time; an undefined Symbol raises `StandardHealth::EnvSpec::UnknownModeAlias`.
+- `consumed_by:` keyword on `required`/`recommended`. Accepts a String or `Array<String>` pointing at where the env var is read in the host app; flows through to audit rows verbatim.
+- `group "Label" do ... end` block inside `EnvSpec.define`. Tags enclosed entries with a `group` field in their audit rows. Pure metadata for ops UX.
+- New `:not_applicable` value for the `status` field, used when an `if:`/`unless:` predicate suppresses an entry.
+
+### Changed
+
+- `EnvSpec` internals refactored: `Entry` struct extended with `consumed_by`, `if_predicate`, `unless_predicate`, and `group`. Backward-compatible — every 0.2.0 spec produces identical audit output (modulo `description` now appearing where it was previously suppressed and `group`/`consumed_by` appearing only when set).
+
+## [0.2.0] - 2026-04-29
+
+### Added
+
+- `c.diagnostics_parent_controller` config option. When set, only `StandardHealth::DiagnosticsController` inherits from it; `HealthController` still uses `parent_controller`. Lets consuming apps put auth (e.g. HTTP Basic) on the diagnostics endpoint without needing `raise_on_missing_callback_actions = false` — the workaround three rarebit-one web apps applied when adopting v0.1.0.
+
+### Changed
+
+- `StandardHealth::DiagnosticsController` now inherits from a new `StandardHealth::DiagnosticsApplicationController` that resolves to `diagnostics_parent_controller || parent_controller`. Backward-compatible — when the new option isn't set, behavior is identical to v0.1.0.
+
 ## [0.1.0] - 2026-04-28
 
 ### Added

data/README.md

@@ -69,8 +69,10 @@ The DSL has two declarations:
 
 Both accept:
 
-- `in: %w[staging production]` — restricts the entry to those `APP_ENVIRONMENT` values; ignored otherwise
+- `in: %w[staging production]` — restricts the entry to those `APP_ENVIRONMENT` values; ignored otherwise. May also be a Symbol resolved via `mode_alias` (see below).
 - `description: "..."` — surfaced verbatim in the audit JSON
+- `consumed_by: "config/initializers/sentry.rb"` — pointer (or `Array<String>`) to where the value is read; surfaced verbatim
+- `if: -> { ... }` / `unless: -> { ... }` — Proc predicates evaluated at audit time. When `unless:` returns truthy or `if:` returns falsy, the entry is reported with `status: :not_applicable`
 
 Audit output (one row per applicable entry):
 
@@ -83,7 +85,108 @@ Audit output (one row per applicable entry):
 }
 ```
 
-Possible `status` values are `ok`, `missing` (required + absent), and `should_set` (recommended + absent).
+Possible `status` values are `ok`, `missing` (required + absent), `should_set` (recommended + absent), and `not_applicable` (suppressed by an `if:`/`unless:` predicate).
+
+### Predicates: `if:` and `unless:`
+
+Use predicates when an env var is only meaningful under runtime conditions that aren't expressible as a fixed list of `APP_ENVIRONMENT` values — e.g. when a host app supports a "mock mode" toggle.
+
+```ruby
+required :MYINFO_PRIVATE_JWKS,
+  in: %w[production],
+  unless: -> { ENV["MYINFO_MOCK_MODE"].present? }
+
+recommended :SENTRY_DSN,
+  if: -> { ENV["SENTRY_DISABLED"].blank? }
+```
+
+A suppressed entry surfaces as:
+
+```json
+{
+  "name": "MYINFO_PRIVATE_JWKS",
+  "level": "required",
+  "status": "not_applicable",
+  "reason": "unless predicate matched",
+  "mode": "production"
+}
+```
+
+The `reason` is `"unless predicate matched"` or `"if predicate did not match"`. Both predicates may be combined; the entry only evaluates when `if:` is truthy and `unless:` is falsy.
+
+### Mode aliases: `mode_alias`
+
+Declare reusable groupings of `APP_ENVIRONMENT` values inside the `define` block, then reference them as Symbols in `in:`. Common patterns ship as conventions (not built-ins): `:deployed` for staging-and-up, `:live` for production-only.
+
+```ruby
+StandardHealth::EnvSpec.define do
+  mode_alias :deployed, %w[staging preview production]
+  mode_alias :live,     %w[production]
+
+  required :APP_ENVIRONMENT
+  required :SENTRY_DSN,       in: :deployed
+  required :STRIPE_LIVE_KEY,  in: :live
+end
+```
+
+`in:` accepts:
+
+- `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`.
+
+### `description:` and `consumed_by:`
+
+Both flow through to audit rows verbatim. `description:` is a human hint; `consumed_by:` points at the file(s) that read the value, which makes "what does this env var actually do" much faster to answer in incident response.
+
+```ruby
+required :APP_HOST,
+  in: :deployed,
+  description: "Canonical web host",
+  consumed_by: "config/initializers/sentry.rb"
+```
+
+```json
+{
+  "name": "APP_HOST",
+  "level": "required",
+  "status": "ok",
+  "mode": "production",
+  "description": "Canonical web host",
+  "consumed_by": "config/initializers/sentry.rb"
+}
+```
+
+`consumed_by:` may be a String or `Array<String>`; an Array is preserved as a JSON array.
+
+### Groups
+
+Wrap related declarations in a `group "Label" do ... end` block to tag them with a category. Groups are pure metadata — they don't affect applicability, status, or evaluation order. Nested `group` blocks are supported; the innermost label propagates to enclosed entries. Calling `group` without a block raises `ArgumentError`.
+
+```ruby
+StandardHealth::EnvSpec.define do
+  group "Singpass / MyInfo" do
+    required :MYINFO_CLIENT_ID
+    required :MYINFO_PRIVATE_JWKS, unless: -> { ENV["MYINFO_MOCK_MODE"].present? }
+  end
+
+  group "Database" do
+    required :DATABASE_URL, in: :deployed
+  end
+end
+```
+
+Audit rows for entries declared inside a `group` block carry a `group` key:
+
+```json
+{ "name": "MYINFO_CLIENT_ID", "level": "required", "status": "ok", "mode": "production", "group": "Singpass / MyInfo" }
+```
+
+Entries declared outside any `group` block omit the `group` key entirely.
+
+### Backward compatibility
+
+All v0.2.0 specs continue to produce identical audit output in v0.3.0. The new fields (`description`, `consumed_by`, `group`, `reason`) appear only when the corresponding feature is used; the new `:not_applicable` status only appears when a predicate suppresses an entry.
 
 ## Custom checks
 
@@ -125,8 +228,49 @@ StandardHealth.configure do |c|
 end
 ```
 
+> **Note (Rails 7.1+):** the `only: :env` filter above raises `AbstractController::ActionNotFound` because `HealthController` (alive/ready) shares this parent and has no `:env` action. Use [Splitting auth between health and diagnostics](#splitting-auth-between-health-and-diagnostics) instead — that's why v0.2.0 added `diagnostics_parent_controller`.
+
 For a more granular setup, mount the engine inside an authenticated route block in your host app's `routes.rb`.
 
+### Splitting auth between health and diagnostics
+
+The pattern above hits a snag on Rails 7.1+ when you want to protect *only* `/diagnostics/env`. Both `HealthController` and `DiagnosticsController` inherit from `parent_controller`, so a `before_action :authenticate, only: :env` on that single parent applies to both — and Rails raises `AbstractController::ActionNotFound` because `:env` doesn't exist on `HealthController`.
+
+Pre-v0.2.0 the workaround was to disable the check on the host controller:
+
+```ruby
+class StandardHealthHostController < ActionController::API
+  self.raise_on_missing_callback_actions = false # workaround
+  http_basic_authenticate_with(name: ..., password: ..., only: :env)
+end
+```
+
+From v0.2.0 onwards, point `diagnostics_parent_controller` at a separate base class instead. Only `DiagnosticsController` inherits from it, so the `only: :env` callback no longer leaks onto `HealthController`:
+
+```ruby
+# app/controllers/health_base_controller.rb
+class HealthBaseController < ActionController::API
+end
+
+# app/controllers/diagnostics_base_controller.rb
+class DiagnosticsBaseController < ActionController::API
+  http_basic_authenticate_with(
+    name: ENV.fetch("HEALTH_USER"),
+    password: ENV.fetch("HEALTH_PASS")
+  )
+end
+
+# config/initializers/standard_health.rb
+StandardHealth.configure do |c|
+  c.parent_controller = "HealthBaseController"
+  c.diagnostics_parent_controller = "DiagnosticsBaseController"
+end
+```
+
+Now `/health/alive` and `/health/ready` are unauthenticated (probe-friendly) while `/health/diagnostics/env` requires HTTP Basic — no `raise_on_missing_callback_actions` flag needed.
+
+When `diagnostics_parent_controller` is unset, `DiagnosticsController` falls back to `parent_controller`, matching v0.1.0 behavior exactly.
+
 ## Status semantics
 
 `/ready` returns:

data/app/controllers/standard_health/application_controller.rb

@@ -3,26 +3,16 @@
 module StandardHealth
   # Base controller for all StandardHealth endpoints.
   #
-  # Lazily inherits from `StandardHealth.config.parent_controller` so host
+  # Lazily inherits from `StandardHealth.config.parent_controller` (resolved
+  # by `StandardHealth.parent_controller` in lib/standard_health.rb) so host
   # apps can wire their own auth/rate-limiting/before_actions in once and
-  # have them apply to /alive, /ready, and /diagnostics/env. The default
-  # is `ActionController::API` so the engine works in API-only host apps
+  # have them apply to /alive and /ready. The default is
+  # `ActionController::API` so the engine works in API-only host apps
   # without configuration.
   #
-  # Resolution happens at the moment this class is first referenced, which
-  # is request time — by then the host app's controllers are loaded and
-  # the constant resolves cleanly. Caching the resolved class on the
-  # singleton avoids re-running `constantize` per request.
-  def self.parent_controller
-    @parent_controller ||= config.parent_controller.constantize
-  end
-
-  # Allow tests/host apps to bust the cached parent controller (e.g. when
-  # toggling config between examples).
-  def self.reset_parent_controller!
-    @parent_controller = nil
-  end
-
+  # `DiagnosticsController` has its own base class
+  # (`DiagnosticsApplicationController`) with its own resolver — see
+  # `config.diagnostics_parent_controller`.
   class ApplicationController < parent_controller
   end
 end

data/app/controllers/standard_health/diagnostics_application_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module StandardHealth
+  # Separate base class for `DiagnosticsController` so host apps can target
+  # diagnostics-only auth at this class via `diagnostics_parent_controller`.
+  # When `diagnostics_parent_controller` is unset, this resolves to the same
+  # class as `parent_controller`, so the inheritance chain is behaviorally
+  # identical to v0.1.0.
+  class DiagnosticsApplicationController < diagnostics_parent_controller
+  end
+end

data/app/controllers/standard_health/diagnostics_controller.rb

@@ -3,9 +3,15 @@
 module StandardHealth
   # Diagnostics endpoints. Output here is potentially sensitive (it
   # enumerates which env vars are missing), so host apps are responsible
-  # for wrapping these routes with authentication via `parent_controller`
-  # — typically a basic-auth `before_action` on `ApplicationController`.
-  class DiagnosticsController < ApplicationController
+  # for wrapping these routes with authentication.
+  #
+  # Inherits from `DiagnosticsApplicationController`, which resolves to
+  # `config.diagnostics_parent_controller || config.parent_controller`.
+  # This lets host apps put auth on diagnostics only — e.g. an HTTP Basic
+  # `before_action :auth, only: :env` on a dedicated diagnostics parent —
+  # without that callback leaking onto `HealthController` and tripping
+  # Rails 7.1's `raise_on_missing_callback_actions`.
+  class DiagnosticsController < DiagnosticsApplicationController
     # Audits the configured EnvSpec against the current process ENV and
     # returns the result as JSON. When no EnvSpec is configured the
     # endpoint returns an empty audit rather than a 404 so callers don't

data/lib/standard_health/configuration.rb

@@ -25,6 +25,18 @@ module StandardHealth
     # engine works in API-only host apps without configuration.
     attr_accessor :parent_controller
 
+    # Optional class name of a controller that ONLY `DiagnosticsController`
+    # should inherit from. When set, `HealthController` continues to use
+    # `parent_controller` while `DiagnosticsController` uses this one. Lets
+    # host apps put auth (e.g. HTTP Basic) on the diagnostics endpoint
+    # without needing to set `raise_on_missing_callback_actions = false`
+    # to suppress Rails 7.1's missing-action error caused by a single
+    # parent declaring `before_action :auth, only: :env` for both controllers.
+    #
+    # When unset (the default), `DiagnosticsController` falls back to
+    # `parent_controller` — fully backward-compatible with v0.1.0.
+    attr_accessor :diagnostics_parent_controller
+
     # An optional `StandardHealth::EnvSpec` instance describing required and
     # recommended environment variables for the host app. Audited via the
     # /diagnostics/env endpoint.
@@ -32,6 +44,7 @@ module StandardHealth
 
     def initialize
       @parent_controller = "ActionController::API"
+      @diagnostics_parent_controller = nil
       @env_spec = nil
       @checks = []
     end

data/lib/standard_health/env_spec.rb

@@ -6,32 +6,62 @@ module StandardHealth
   # Example:
   #
   #   StandardHealth::EnvSpec.define do
+  #     mode_alias :deployed, %w[staging preview production]
+  #     mode_alias :live, %w[production]
+  #
   #     required :SECRET_KEY_BASE
   #     required :APP_ENVIRONMENT, in: %w[staging production]
   #     recommended :SENTRY_DSN, description: "Error tracking DSN"
+  #
+  #     group "Singpass / MyInfo" do
+  #       required :MYINFO_CLIENT_ID
+  #       required :MYINFO_PRIVATE_JWKS,
+  #         in: :live,
+  #         unless: -> { ENV["MYINFO_MOCK_MODE"].present? }
+  #     end
   #   end
   #
   # Each entry has:
   #   - `name` (Symbol)
   #   - `level` (:required | :recommended)
-  #   - `modes` (Array<String>, optional) — when set, the entry only applies
-  #     while `APP_ENVIRONMENT` matches one of these modes. Otherwise it
-  #     applies to every mode.
-  #   - `description` (String, optional) — human-readable hint surfaced
+  #   - `in:` (Array<String>, Symbol, or nil) — when an Array, the entry only
+  #     applies while `APP_ENVIRONMENT` matches one of these modes. A Symbol
+  #     is resolved against `mode_alias` declarations at audit time. When
+  #     omitted, the entry applies to every mode.
+  #   - `description:` (String, optional) — human-readable hint surfaced
   #     verbatim by `/diagnostics/env`.
+  #   - `consumed_by:` (String or Array<String>, optional) — pointer(s) to
+  #     where the value is read in the host app. Surfaced verbatim.
+  #   - `if:` / `unless:` (Proc, optional) — predicates evaluated at audit
+  #     time. When `unless:` returns truthy or `if:` returns falsy the entry
+  #     is reported with `status: :not_applicable`.
+  #   - `group` (String, optional) — set implicitly by enclosing `group`
+  #     block; surfaced verbatim.
   class EnvSpec
-    Entry = Struct.new(:name, :level, :modes, :description, keyword_init: true) do
-      # Whether this entry's audit applies under the given runtime mode.
-      # Entries without a `modes:` constraint always apply.
-      def applies_to?(mode)
-        return true if modes.nil? || modes.empty?
-        modes.include?(mode.to_s)
-      end
-    end
+    # Raised when `in:` references a Symbol that hasn't been declared via
+    # `mode_alias`.
+    class UnknownModeAlias < ArgumentError; end
+
+    # Internal entry record. `modes` may be an Array<String> or a Symbol
+    # alias that gets resolved at audit time.
+    Entry = Struct.new(
+      :name,
+      :level,
+      :modes,
+      :description,
+      :consumed_by,
+      :if_predicate,
+      :unless_predicate,
+      :group,
+      keyword_init: true
+    )
 
     # @return [Array<Entry>]
     attr_reader :entries
 
+    # @return [Hash{Symbol => Array<String>}]
+    attr_reader :mode_aliases
+
     # Build a spec via the DSL.
     def self.define(&block)
       new.tap { |spec| spec.instance_eval(&block) if block }
@@ -39,13 +69,42 @@ module StandardHealth
 
     def initialize
       @entries = []
+      @mode_aliases = {}
+      @group_stack = []
+    end
+
+    # Declare a mode alias usable in `in:`. Re-declaring overrides the
+    # previous value (last writer wins) so layered specs are easy to compose.
+    #
+    # @param name [Symbol]
+    # @param modes [Array<String>]
+    def mode_alias(name, modes)
+      @mode_aliases[name.to_sym] = Array(modes).map(&:to_s)
+    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
+    # propagates to enclosed entries.
+    #
+    # @param label [String]
+    def group(label, &block)
+      raise ArgumentError, "group requires a block" unless block
+
+      @group_stack.push(label.to_s)
+      block.call
+    ensure
+      @group_stack.pop
     end
 
     # Declare a required env var.
     #
     # @param name [Symbol, String]
-    # @param in [Array<String>, nil] limit applicability to these modes
+    # @param in [Array<String>, Symbol, nil] limit applicability to these modes
     # @param description [String, nil]
+    # @param consumed_by [String, Array<String>, nil]
+    # @param if [Proc, nil]
+    # @param unless [Proc, nil]
     def required(name, **opts)
       add(:required, name, **opts)
     end
@@ -60,41 +119,105 @@ module StandardHealth
     #
     # @param env_hash [Hash{String, Symbol => String}] e.g. ENV.to_h
     # @param mode [String, Symbol] current APP_ENVIRONMENT value
-    # @return [Array<Hash>] one row per applicable entry, each shaped like:
-    #   { name:, level:, status: :ok | :missing | :should_set, mode: }
+    # @return [Array<Hash>] one row per applicable entry. Each row has at
+    #   least `name`, `level`, `status`, `mode`. When an entry is suppressed
+    #   by an `if:`/`unless:` predicate, `status` is `:not_applicable` and a
+    #   `reason` field explains why. `description`, `consumed_by`, and
+    #   `group` are included when set on the entry.
     def audit(env_hash, mode:)
       mode_str = mode.to_s
       env = stringify(env_hash)
 
       @entries.each_with_object([]) do |entry, out|
-        next unless entry.applies_to?(mode_str)
-
-        value = env[entry.name.to_s]
-        status = classify(entry, value)
-
-        row = {
-          name: entry.name,
-          level: entry.level,
-          status: status,
-          mode: mode_str
-        }
-        row[:description] = entry.description if entry.description
+        next unless mode_applies?(entry, mode_str)
+
+        row = base_row(entry, mode_str)
+
+        suppression = predicate_suppression(entry)
+        if suppression
+          row[:status] = :not_applicable
+          row[:reason] = suppression
+        else
+          value = env[entry.name.to_s]
+          row[:status] = classify(entry, value)
+        end
+
         out << row
       end
     end
 
     private
 
-    def add(level, name, in: nil, description: nil)
-      modes = binding.local_variable_get(:in)
+    def add(level, name, **opts)
+      modes_opt = opts[:in]
       @entries << Entry.new(
         name: name.to_sym,
         level: level,
-        modes: modes ? Array(modes).map(&:to_s) : nil,
-        description: description
+        modes: normalize_modes(modes_opt),
+        description: opts[:description],
+        consumed_by: normalize_consumed_by(opts[:consumed_by]),
+        if_predicate: opts[:if],
+        unless_predicate: opts[:unless],
+        group: @group_stack.last
       )
     end
 
+    def normalize_modes(modes_opt)
+      return nil if modes_opt.nil?
+      return modes_opt if modes_opt.is_a?(Symbol)
+      Array(modes_opt).map(&:to_s)
+    end
+
+    def normalize_consumed_by(value)
+      return nil if value.nil?
+      array = Array(value).map(&:to_s)
+      array.empty? ? nil : array
+    end
+
+    def mode_applies?(entry, mode_str)
+      modes = resolve_modes(entry.modes)
+      return true if modes.nil? || modes.empty?
+      modes.include?(mode_str)
+    end
+
+    def resolve_modes(modes)
+      return nil if modes.nil?
+      if modes.is_a?(Symbol)
+        unless @mode_aliases.key?(modes)
+          raise UnknownModeAlias, "Unknown mode alias: #{modes.inspect}"
+        end
+        @mode_aliases[modes]
+      else
+        modes
+      end
+    end
+
+    def predicate_suppression(entry)
+      if entry.unless_predicate && entry.unless_predicate.call
+        return "unless predicate matched"
+      end
+      if entry.if_predicate && !entry.if_predicate.call
+        return "if predicate did not match"
+      end
+      nil
+    end
+
+    # Builds the metadata-only portion of an audit row. The caller is
+    # responsible for setting `:status` (and optionally `:reason`) — keeping
+    # status off the base intentionally so a future code path that forgets
+    # to set it produces a missing-key error instead of a silent `nil`.
+    def base_row(entry, mode_str)
+      row = { name: entry.name, level: entry.level, mode: mode_str }
+      row[:description] = entry.description if entry.description
+      row[:consumed_by] = serialize_consumed_by(entry.consumed_by) if entry.consumed_by
+      row[:group] = entry.group if entry.group
+      row
+    end
+
+    def serialize_consumed_by(value)
+      value.length == 1 ? value.first : value
+    end
+
     def classify(entry, value)
       present = !value.nil? && !value.to_s.empty?
       return :ok if present

data/lib/standard_health/version.rb

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

data/lib/standard_health.rb

@@ -32,5 +32,41 @@ module StandardHealth
     def reset_config!
       @config = Configuration.new
     end
+
+    # Resolves `config.parent_controller` to an actual class lazily — at
+    # the moment the engine's `ApplicationController` is first referenced
+    # (request time), by which point the host app's controllers are
+    # loaded. Caching avoids re-running `constantize` per request, and
+    # the name-mismatch reset lets tests swap config between examples.
+    def parent_controller
+      expected = config.parent_controller
+      if @parent_controller && @parent_controller.name != expected
+        @parent_controller = nil
+      end
+      @parent_controller ||= expected.constantize
+    end
+
+    def reset_parent_controller!
+      @parent_controller = nil
+    end
+
+    # Resolves the parent class for `DiagnosticsController` only. Falls
+    # back to `config.parent_controller` when no diagnostics-specific
+    # parent is configured, preserving v0.1.0 behavior. When set, lets
+    # host apps apply `before_action :auth, only: :env` to the diagnostics
+    # endpoint without that callback leaking onto `HealthController`
+    # (which would otherwise trip Rails 7.1's
+    # `raise_on_missing_callback_actions`).
+    def diagnostics_parent_controller
+      expected = config.diagnostics_parent_controller || config.parent_controller
+      if @diagnostics_parent_controller && @diagnostics_parent_controller.name != expected
+        @diagnostics_parent_controller = nil
+      end
+      @diagnostics_parent_controller ||= expected.constantize
+    end
+
+    def reset_diagnostics_parent_controller!
+      @diagnostics_parent_controller = nil
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_health
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -37,6 +37,7 @@ files:
 - README.md
 - Rakefile
 - app/controllers/standard_health/application_controller.rb
+- app/controllers/standard_health/diagnostics_application_controller.rb
 - app/controllers/standard_health/diagnostics_controller.rb
 - app/controllers/standard_health/health_controller.rb
 - config/routes.rb