standard_health 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 298b48147224460e942fb5dd9440596ef128f0967dc7212a507756b9b45ae1b5
-  data.tar.gz: 5008923ddf09d5637f9e6c07b95bf9073b15d0e79b2d0e00646170478e5d7aee
+  metadata.gz: 8542efb5b2511d31b4c9b3ef2a10f650ed342c1eeadc4aecaadef1476b82bc59
+  data.tar.gz: 8996c9e8f67904d842f589e60d880127680afa55365cb3be835260db9d36b3c1
 SHA512:
-  metadata.gz: 61f79addc2cba3dc84019036dd38b0917b5c812193b6b8af551b4efdd8578f93499a8efaed5f95b38efa07d71bf5d3bfe19495ff7f54eea145895169289aa7e5
-  data.tar.gz: ff348b35a931bed97044118e15b275ac1daed5fae93929c1f2976bc1db1947dbbeb8a05fe8029bc277311e6174e73e8be94c3afc060c880282a1fa1906406d63
+  metadata.gz: b528859586bf219cab6b76902a230f3e660d36e4c108db6489ad1c4643fc19455c868bfa1fbe2b5fdc5291173aa04bfaa516ff322f44cecea41cd3cf5381b474
+  data.tar.gz: fe062a3ab494d205e3d436037a4ea42fbe3802043a7d8b3ee873ff4d5b6dd1ae7d1a7bd4659a3e4c533d92cfc035fa47d7c582801a418e4ba24b8943163ae5d5

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

@@ -125,8 +125,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StandardHealth
-  VERSION = "0.1.0"
+  VERSION = "0.2.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.2.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