standard_health 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 162374f071e6634d43876ef75f8fa6f50b1ec7bfd6a8d01bd94a91c854151d09
4
- data.tar.gz: 58c40844359768a3d905c75575599dc1bf61dab15ebabc372c3e5e56cd4e169d
3
+ metadata.gz: e40d17a77554d7b4f1501fbd1e0d976d7a7d3787a3955f46b708dea9b92a8c97
4
+ data.tar.gz: a75f0a49175b3be0122203dd996695b7b2348d44005f42e123ba2faa4e2ca0f7
5
5
  SHA512:
6
- metadata.gz: a93890d618342991d02699f9a68d0cf432596f4fba5eff7659d4d4c8675d22e5e0bac3d996abed41e02ddd7f53b84c771f21e093a6c6e22b39404ec9ccc7498c
7
- data.tar.gz: 13b347704251b47c6a877ce5fb559686d9fee639610109300da1fd989627010a3823f678ab420330a26ac851548647da3ab12405081cd13a2d9024c90d4bb5dc
6
+ metadata.gz: 2096e6758bec24145a0a4887de07fbcaefeeab09916f24bd6ddbe7b99e565e0a9365438acbd6ae67526223904a09f2ec611ac38e32a803810cd27f3dbd6a9a69
7
+ data.tar.gz: 85e32074db7e60d8e1a5cffa11d41ed74a521b1a17302699cfdec491095d65e5a5570cca9d17ed2cf4ebdd407b2370b34157952f99e9d68c9afb6cc25a9fb69c
data/CHANGELOG.md CHANGED
@@ -7,6 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.9.0] - 2026-11-23
11
+
12
+ ### Added
13
+
14
+ - **Other gems can contribute checks and env vars.** A gem registers
15
+ `ActiveSupport.on_load(:standard_health) { |health| ... }` with no
16
+ dependency on standard_health, and the block receives an object exposing
17
+ only `contribute_check` and `contribute_env_vars` (an arity-0 block is
18
+ `instance_eval`'d on it). standard_health runs the hook once when it loads,
19
+ so it works in either require order. Contribute at require time. See
20
+ "Contributing checks from another gem" in the README.
21
+ - `contribute_check(name, klass, critical: false, timeout: nil, **options)`
22
+ adds a check to the set `register_default_checks` registers. It is
23
+ non-critical unless the contributor says otherwise, and apps opt out or
24
+ override it by name (`register_default_checks(standard_id_migrations:
25
+ false)`). A check contributed after `register_default_checks` ran is not
26
+ registered; standard_health warns instead. Aggregate-tier contributions
27
+ are not supported yet.
28
+ - `contribute_env_vars(contributor) { ... }` declares env vars with the
29
+ `EnvSpec` DSL, grouped under the contributor. They join the app's spec on
30
+ `/diagnostics/env` and in `Checks::EnvSpecAudit`, and the app's own
31
+ declaration of a var wins. They may use plain environment names only, not
32
+ app mode aliases. With no app `env_spec`, the contributions alone form the
33
+ spec. If two gems declare the same var, the first to contribute wins and
34
+ a warning (once per process) names the var and both gems.
35
+ - The registry lives outside `Configuration`, so `reset_config!` keeps
36
+ contributions.
37
+ - `Configuration#effective_env_spec`: the app's `env_spec` merged with
38
+ contributed env vars. `env_spec` still returns exactly what the app set.
39
+ - `EnvSpec#reverse_merge(other)`: a new spec with the other spec's entries
40
+ for vars the receiver does not declare.
41
+ - `Configuration#error_reporter`: an optional callable `(error, context)` that
42
+ receives the gem's own handled errors (a check raising on the aggregate
43
+ tier, a diagnostics assertion raising) instead of `Rails.error.report`. The
44
+ context keys are unchanged. nil (the default) keeps `Rails.error`.
45
+
46
+ ### Changed
47
+
48
+ - **Nested `EnvSpec` groups combine their labels.** `group "A" do group "B"
49
+ ... end end` now tags entries `"A / B"` instead of `"B"`. No consumer app
50
+ nests groups today; a nested label in an audit row changes accordingly.
51
+ - `register_default_checks` takes any known key (built-ins plus contributed
52
+ check names) instead of four fixed keywords. Existing calls behave the
53
+ same. An unknown key still raises `ArgumentError`, now listing the known
54
+ keys.
55
+
56
+ ### Deprecated
57
+
58
+ - The hardcoded `audit_retention` entry in `Configuration::DEFAULT_CHECKS`
59
+ (the only default naming another gem's class). It keeps working. Once
60
+ standard_audit contributes `audit_retention`, the contribution replaces it
61
+ (same key and position, registered once), and a later release removes the
62
+ hardcoded entry.
63
+
64
+ ## [0.8.0] - 2026-10-22
65
+
66
+ ### Changed
67
+
68
+ - **Re-registering a check replaces it.** `register_check` and
69
+ `register_aggregate_check` replace an existing registration of the same name
70
+ in place (last writer wins) instead of appending a second one, matching
71
+ `register_diagnostics_assertion`. A `configure` block that runs twice, e.g.
72
+ from `to_prepare` on reload, no longer runs every check twice.
73
+ - **`env_spec` aliases are checked at boot.** Assigning `c.env_spec = …` calls
74
+ the new `EnvSpec#validate!`, which raises `EnvSpec::UnknownModeAlias` naming
75
+ every `in:` alias that has no `mode_alias`. Before, an undeclared alias raised
76
+ only on the first audit, which was a production `/diagnostics/env` request
77
+ (it 500'd one app's doctor tier once). All five estate apps declare every
78
+ alias they use, so none of them is affected.
79
+
10
80
  ## [0.7.1] - 2026-09-25
11
81
 
12
82
  ### Fixed
data/README.md CHANGED
@@ -210,6 +210,15 @@ c.register_default_checks
210
210
  | `solid_queue` | `:solid_queue` | `Checks::SolidQueue` | `true` | `SolidQueue` is loaded |
211
211
  | `solid_cache` | `:solid_cache` | `Checks::SolidCache` | `false` | `SolidCache` is loaded |
212
212
  | `audit_retention` | `:audit_retention` | `StandardAudit::Checks::Retention` | `false` | `standard_audit` is loaded |
213
+ | *contributed name* | *contributed name* | *contributor's class* | contributor's, else `false` | always (the gem is loaded) |
214
+
215
+ The last row is every check another gem has
216
+ [contributed](#contributing-checks-from-another-gem), after the built-ins in
217
+ contribution order. `audit_retention` is the one built-in that names another
218
+ gem's class; it is deprecated and goes once standard_audit contributes it.
219
+ Until then nothing changes, and when standard_audit does contribute it, the
220
+ contribution takes over the same key and position, so it never registers
221
+ twice.
213
222
 
214
223
  A check whose backing library isn't loaded is skipped rather than registered
215
224
  to fail forever. A name that's already registered is skipped too, so it's safe
@@ -223,7 +232,8 @@ c.register_default_checks solid_cache: false, # jumpdrive: has S
223
232
  ```
224
233
 
225
234
  Returns the names it registered. Check order in the response follows
226
- registration order.
235
+ registration order. An unknown key raises `ArgumentError` listing the known
236
+ ones, including contributed names.
227
237
 
228
238
  ## EnvSpec
229
239
 
@@ -362,7 +372,7 @@ end
362
372
 
363
373
  - `nil` (omitted) — entry always applies
364
374
  - `Array<String>` — literal mode list (existing behaviour)
365
- - `Symbol` — resolved against `mode_alias` at audit time. An undeclared Symbol raises `StandardHealth::EnvSpec::UnknownModeAlias`.
375
+ - `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.
366
376
 
367
377
  ### `description:` and `consumed_by:`
368
378
 
@@ -390,7 +400,7 @@ required :APP_HOST,
390
400
 
391
401
  ### Groups
392
402
 
393
- 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`.
403
+ 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 combine their labels outermost first, joined with `" / "` (`group "Auth" do group "Google" do ... end end` tags entries `"Auth / Google"`). Calling `group` without a block raises `ArgumentError`.
394
404
 
395
405
  ```ruby
396
406
  StandardHealth::EnvSpec.define do
@@ -465,9 +475,11 @@ end
465
475
  `:ok`, `:warn` or `:error`. Other keys are rendered as-is. The gem sets
466
476
  `name:`, and the callable can't override it.
467
477
  - An assertion that raises becomes `{ status: "error", error_class:, error: }`
468
- and is reported to `Rails.error` as handled. The tier is authenticated, so
469
- the message is shown. A non-Hash result or an unknown status also becomes an
470
- `:error` row. One broken assertion never takes the endpoint down.
478
+ and is reported to `Rails.error` as handled (or to
479
+ [`error_reporter`](#routing-the-gems-own-errors-error_reporter)). The tier
480
+ is authenticated, so the message is shown. A non-Hash result or an unknown
481
+ status also becomes an `:error` row. One broken assertion never takes the
482
+ endpoint down.
471
483
  - An `:error` row makes the top-level `status` `incomplete`. `:warn` does not.
472
484
  The endpoint still returns 200.
473
485
  - Assertions run per request, and only on this tier, never on `/alive`,
@@ -522,6 +534,10 @@ end
522
534
 
523
535
  `with_timing` captures `latency_ms` on success and converts any `StandardError` into `{ status: :fail, error: <message> }`.
524
536
 
537
+ Registering a name that is already registered replaces that check in place (the
538
+ same for `register_aggregate_check`), so a `configure` block that runs twice,
539
+ e.g. from `to_prepare` on reload, doesn't run any check twice.
540
+
525
541
  **Per-registration options (0.6.0).** Keywords other than `critical:` and
526
542
  `timeout:` are forwarded to the check's constructor, and validated against its
527
543
  signature at registration — a typo fails at boot, not on every probe:
@@ -550,6 +566,104 @@ c.register_check :runner, "RunnerHealthCheck"
550
566
 
551
567
  **A check must never raise.** `Aggregator` rescues `StandardError` per check, so a buggy check degrades to `:fail` rather than 500ing the endpoint — but don't rely on that as the only line of defence. Route fallible work through `with_timing`.
552
568
 
569
+ ## Contributing checks from another gem
570
+
571
+ A gem can offer a health check and declare the env vars it reads without
572
+ depending on standard_health (and without standard_health knowing about it),
573
+ through a Rails load hook:
574
+
575
+ ```ruby
576
+ # lib/standard_id.rb (or its engine.rb). No `require "standard_health"`.
577
+ ActiveSupport.on_load(:standard_health) do |health|
578
+ health.contribute_check :standard_id_migrations, "StandardId::Checks::Migrations"
579
+
580
+ health.contribute_env_vars "standard_id" do
581
+ recommended :STANDARD_ID_OAUTH_SIGNING_KEY, description: "Signs OAuth tokens"
582
+ forbidden :STANDARD_ID_BYPASS_CODE, in: %w[production],
583
+ description: "Fixed login code for staging; never in production"
584
+ end
585
+ end
586
+ ```
587
+
588
+ If standard_health is not in the bundle the block never runs. If it is, the
589
+ block runs exactly once whichever gem is required first: standard_health runs
590
+ `ActiveSupport.run_load_hooks(:standard_health, ...)` when it loads, which
591
+ fires hooks registered earlier, and later hooks fire immediately.
592
+
593
+ The block receives an object with exactly two methods, `contribute_check`
594
+ and `contribute_env_vars`, and nothing else. An arity-0 block is
595
+ `instance_eval`'d on that same object, as with any load hook, so this works
596
+ too:
597
+
598
+ ```ruby
599
+ ActiveSupport.on_load(:standard_health) do
600
+ contribute_check :audit_schema, "StandardAudit::Checks::Schema"
601
+ contribute_env_vars("standard_audit") { recommended :STANDARD_AUDIT_RETENTION_DAYS }
602
+ end
603
+ ```
604
+
605
+ **Contribute at require time.** Put the hook at the top level of the gem's
606
+ main file or engine file, never in an initializer, `to_prepare` or
607
+ `after_initialize`. Under `Bundler.require` that runs before any app
608
+ initializer, which is where apps call `register_default_checks`. A check
609
+ contributed later is not registered (see below); env vars still appear.
610
+
611
+ What gems contribute lives in a process-wide registry, separate from the
612
+ configuration: `StandardHealth.reset_config!` does not clear it, so app and
613
+ gem specs that reset config between examples keep every contribution.
614
+
615
+ ### `contribute_check(name, klass, critical: false, timeout: nil, **options)`
616
+
617
+ Same arguments as `register_check`. The check is **not registered on its
618
+ own**: it joins the set `register_default_checks` registers, so an app gets it
619
+ only if it calls that, and can opt out or override it by name like a built-in:
620
+
621
+ ```ruby
622
+ c.register_default_checks standard_id_migrations: false
623
+ c.register_default_checks standard_id_migrations: { critical: true, timeout: 2 }
624
+ ```
625
+
626
+ - Non-critical unless the contributor passes `critical: true`. Most gem checks
627
+ report drift (missing migrations, schema gaps) that should degrade, not pull
628
+ the instance out of rotation.
629
+ - Pass the class as a String. It is resolved when the check runs, so the
630
+ gem's constant needn't be loadable when the hook fires.
631
+ - `:database`, `:solid_queue` and `:solid_cache` are reserved and raise
632
+ `ArgumentError`. Re-contributing a name replaces it.
633
+ - An app that registered the name itself keeps its own registration.
634
+ - **A late check is not registered.** A check contributed after the app has
635
+ called `register_default_checks` is not added retroactively; standard_health
636
+ prints a warning to stderr instead. Contribute at require time.
637
+ - **Aggregate-tier checks are not supported yet.** A contributed check joins
638
+ readiness (`register_default_checks`) only. An app that wants a gem's check
639
+ on the aggregate tier registers it there itself with
640
+ `register_aggregate_check`.
641
+
642
+ ### `contribute_env_vars(contributor, &block)`
643
+
644
+ The block is the [EnvSpec](#envspec) DSL (`required`, `recommended`,
645
+ `forbidden`, `group`). Each entry is grouped under `contributor`, and a nested
646
+ `group` is labelled beneath it (`group "MyInfo"` inside
647
+ `contribute_env_vars "standard_singpass"` shows as
648
+ `"standard_singpass / MyInfo"`). The declarations join the app's `env_spec`
649
+ on `/diagnostics/env` and in `Checks::EnvSpecAudit`:
650
+
651
+ - **The app wins.** If the app's `env_spec` declares a var at all, the gem's
652
+ entries for it are dropped, so an app can tighten or relax a gem's
653
+ declaration by declaring the var itself.
654
+ - **No app `env_spec` is fine.** The contributions alone form the spec. With
655
+ neither, the audit stays empty, as before.
656
+ - **Plain environment names only.** `in: %w[production]` works; `in: :live`
657
+ and `mode_alias` raise `ArgumentError` when the gem loads, because aliases
658
+ such as `:deployed` or `:live` are defined by each app, not by gems.
659
+ - **If two gems declare the same var, the first to contribute wins.**
660
+ standard_health warns once per process, naming the var and both gems.
661
+ - Re-contributing under the same `contributor` replaces its declarations.
662
+ Contributions are merged when the audit runs, so a late one still appears.
663
+
664
+ `StandardHealth.config.effective_env_spec` returns the merged spec;
665
+ `StandardHealth.config.env_spec` stays exactly what the app assigned.
666
+
553
667
  ## Opt-in checks
554
668
 
555
669
  Every check in this gem must be registered explicitly; **none are registered
@@ -884,6 +998,19 @@ probe period means ~6 evaluations/minute/instance:
884
998
  The Logger also reports `aggregate.evaluated` (silent on ok); Sentry and
885
999
  Metrics ignore it.
886
1000
 
1001
+ ### Routing the gem's own errors: `error_reporter`
1002
+
1003
+ Two failures are reported as handled errors rather than events: a check that
1004
+ raises on the aggregate tier, and a diagnostics assertion that raises. They go
1005
+ to `Rails.error.report` by default. Set `error_reporter` to a callable taking
1006
+ `(error, context)` to send them elsewhere; `context` is the Hash `Rails.error`
1007
+ would get (`{ health_check:, tier: }` or `{ diagnostics_assertion: }`). A
1008
+ reporter that raises is swallowed, so it can never break a health tier.
1009
+
1010
+ ```ruby
1011
+ c.error_reporter = ->(error, context) { Sentry.capture_exception(error, extra: context) }
1012
+ ```
1013
+
887
1014
  ### Narrowing metrics (0.6.0)
888
1015
 
889
1016
  The per-poll events are the metric volume (~2 evaluations × N checks per probe
@@ -17,12 +17,13 @@ module StandardHealth
17
17
  class DiagnosticsController < DiagnosticsApplicationController
18
18
  include DiagnosticsAuthentication
19
19
 
20
- # Audits the configured EnvSpec against the current process ENV and
21
- # returns the result as JSON. When no EnvSpec is configured the
20
+ # Audits the configured EnvSpec, plus env vars other gems contributed
21
+ # (`Configuration#effective_env_spec`), against the current process ENV
22
+ # and returns the result as JSON. When there is no spec at all the
22
23
  # endpoint returns an empty audit rather than a 404 so callers don't
23
24
  # have to special-case "feature not enabled".
24
25
  def env
25
- spec = StandardHealth.config.env_spec
26
+ spec = StandardHealth.config.effective_env_spec
26
27
  mode = ENV["APP_ENVIRONMENT"].to_s
27
28
  root = defined?(Rails) ? Rails.root : nil
28
29
 
@@ -46,7 +46,8 @@ StandardHealth.configure do |config|
46
46
  #
47
47
  # Or register the common set in one call — :database and :solid_queue
48
48
  # (critical), :solid_cache and :audit_retention (non-critical), each skipped
49
- # when its library isn't loaded:
49
+ # when its library isn't loaded, plus any check another gem contributed
50
+ # (e.g. :standard_id_migrations; opt out with `standard_id_migrations: false`):
50
51
  # config.register_default_checks
51
52
  # config.register_check :cache, StandardHealth::Checks::SolidCache
52
53
  # config.register_check :queue, StandardHealth::Checks::SolidQueue
@@ -180,13 +180,13 @@ module StandardHealth
180
180
  # every raise from a ~6/min/instance probe would be exactly the noise that
181
181
  # notifier exists to prevent. Severity mirrors that notifier: a critical
182
182
  # check is an :error (it makes the tier :unavailable), otherwise :warning.
183
+ #
184
+ # `Configuration#error_reporter`, when set, receives it instead.
183
185
  def self.report_raised_check(error, reg, tier)
184
186
  return if tier == :ready
185
- return unless defined?(::Rails) && ::Rails.respond_to?(:error) && ::Rails.error
186
187
 
187
- ::Rails.error.report(
188
+ StandardHealth.config.report_error(
188
189
  error,
189
- handled: true,
190
190
  severity: reg.critical ? :error : :warning,
191
191
  context: { health_check: reg.name.to_s, tier: tier.to_s }
192
192
  )
@@ -74,7 +74,8 @@ module StandardHealth
74
74
  private
75
75
 
76
76
  def violating_rows
77
- spec = ::StandardHealth.config.env_spec
77
+ # Includes env vars other gems contributed, as /diagnostics/env does.
78
+ spec = ::StandardHealth.config.effective_env_spec
78
79
  return [] unless spec
79
80
 
80
81
  # No `root:`. Resolving `consumed_by` paths does file IO per entry,
@@ -86,7 +86,37 @@ module StandardHealth
86
86
  # An optional `StandardHealth::EnvSpec` instance describing required and
87
87
  # recommended environment variables for the host app. Audited via the
88
88
  # /diagnostics/env endpoint.
89
- attr_accessor :env_spec
89
+ attr_reader :env_spec
90
+
91
+ # Validates the spec as it is assigned (`EnvSpec#validate!`), so an
92
+ # `in:` alias with no `mode_alias` fails the initializer at boot rather
93
+ # than raising on the first audit, which is a /diagnostics/env request
94
+ # in production.
95
+ def env_spec=(spec)
96
+ spec.validate! if spec.respond_to?(:validate!)
97
+ @env_spec = spec
98
+ end
99
+
100
+ # The spec that is actually audited, on `/diagnostics/env` and by
101
+ # `Checks::EnvSpecAudit`: `env_spec` plus the env vars other gems
102
+ # contributed (`Contributions#contribute_env_vars`), grouped per gem.
103
+ # The app's own declaration of a var wins over a gem's.
104
+ #
105
+ # With no `env_spec` set, the contributions alone form the spec; with
106
+ # neither, this is nil (the audit is empty, as before). `env_spec` itself
107
+ # stays exactly what the app assigned.
108
+ #
109
+ # Rebuilt on each call rather than cached, so a contribution that arrives
110
+ # after the initializer still shows up. Both are a handful of entries.
111
+ #
112
+ # @return [EnvSpec, nil]
113
+ def effective_env_spec
114
+ contributed = @contributions.env_spec
115
+ return @env_spec unless contributed
116
+ return contributed unless @env_spec
117
+
118
+ @env_spec.reverse_merge(contributed)
119
+ end
90
120
 
91
121
  # --- Instrumentation -----------------------------------------------
92
122
  #
@@ -159,6 +189,37 @@ module StandardHealth
159
189
  # Extra `call(event_name, payload)` subscribers supplied by the host.
160
190
  attr_reader :extra_notifiers
161
191
 
192
+ # Where the gem reports its own handled errors: a check that raises on
193
+ # the aggregate tier, and a diagnostics assertion that raises. nil (the
194
+ # default) keeps `Rails.error.report(error, handled: true, ...)`. Set a
195
+ # callable taking `(error, context)` to route them elsewhere; `context`
196
+ # is the Hash `Rails.error` would get (`{ health_check:, tier: }` or
197
+ # `{ diagnostics_assertion: }`).
198
+ #
199
+ # c.error_reporter = ->(error, context) { Sentry.capture_exception(error, extra: context) }
200
+ attr_reader :error_reporter
201
+
202
+ def error_reporter=(reporter)
203
+ unless reporter.nil? || reporter.respond_to?(:call)
204
+ raise ArgumentError, "error_reporter must respond to `call(error, context)`; got #{reporter.class}"
205
+ end
206
+
207
+ @error_reporter = reporter
208
+ end
209
+
210
+ # Reports a handled error through `error_reporter`, or `Rails.error` when
211
+ # none is set (`rails_options` such as `severity:` go to `Rails.error`
212
+ # only). Callers rescue: a broken reporter must not break a health tier.
213
+ #
214
+ # @api private
215
+ def report_error(error, context:, **rails_options)
216
+ if error_reporter
217
+ error_reporter.call(error, context)
218
+ elsif defined?(::Rails) && ::Rails.respond_to?(:error) && ::Rails.error
219
+ ::Rails.error.report(error, handled: true, context: context, **rails_options)
220
+ end
221
+ end
222
+
162
223
  # --- Response redaction --------------------------------------------
163
224
  #
164
225
  # When false (the default) a failing check reports `error_class` +
@@ -215,7 +276,10 @@ module StandardHealth
215
276
  # one — or better, a driver-level timeout.
216
277
  attr_accessor :total_check_budget
217
278
 
218
- def initialize
279
+ # `contributions` is the process-wide registry by default; a fresh one
280
+ # isolates a test from whatever the loaded gems contributed.
281
+ def initialize(contributions: StandardHealth.contributions)
282
+ @contributions = contributions
219
283
  @parent_controller = "ActionController::API"
220
284
  @diagnostics_parent_controller = nil
221
285
  @diagnostics_basic_auth = nil
@@ -234,6 +298,7 @@ module StandardHealth
234
298
  @metrics_enabled = true
235
299
  @metric_events = nil
236
300
  @extra_notifiers = []
301
+ @error_reporter = nil
237
302
 
238
303
  @expose_check_errors = false
239
304
  @detail_token = nil
@@ -270,19 +335,25 @@ module StandardHealth
270
335
  # Validated against the constructor's signature HERE, so a typo fails
271
336
  # at boot instead of turning into an ArgumentError on every probe (which
272
337
  # the aggregator would dutifully report as a failing check forever).
338
+ #
339
+ # Re-registering a name replaces that registration in place (last writer
340
+ # wins), so `configure` can safely re-run, e.g. from `to_prepare` on
341
+ # reload, without running the check twice.
273
342
  def register_check(name, klass, critical: false, timeout: nil, **options)
274
343
  validate_check_options!(klass, options)
275
344
  registration = Registration.new(
276
345
  name: name.to_sym, klass: klass, critical: critical, timeout: timeout, options: options
277
346
  )
278
- @checks << registration
279
- registration
347
+ upsert_registration(@checks, registration)
280
348
  end
281
349
 
282
350
  # The check set every consumer app registers by hand. Each entry: default
283
351
  # registration name, criticality, the check class (a String, resolved only
284
352
  # if the backing library is loaded), and the guard that decides whether
285
353
  # the backing library is present.
354
+ #
355
+ # Checks other gems contribute (`Contributions#contribute_check`) join this
356
+ # set at `register_default_checks` time.
286
357
  DEFAULT_CHECKS = {
287
358
  database: {
288
359
  name: :database, critical: true,
@@ -299,6 +370,10 @@ module StandardHealth
299
370
  klass: "StandardHealth::Checks::SolidCache",
300
371
  available: -> { defined?(::SolidCache) }
301
372
  },
373
+ # DEPRECATED: the one entry naming another gem's class. It stays until
374
+ # standard_audit contributes `audit_retention` itself; once it does, its
375
+ # contribution replaces this entry (same key, same position, never
376
+ # registered twice) and this entry will be removed.
302
377
  audit_retention: {
303
378
  name: :audit_retention, critical: false,
304
379
  klass: "StandardAudit::Checks::Retention",
@@ -313,6 +388,10 @@ module StandardHealth
313
388
  # :solid_cache StandardHealth::Checks::SolidCache non-critical
314
389
  # :audit_retention StandardAudit::Checks::Retention non-critical
315
390
  #
391
+ # followed by every check another gem contributed
392
+ # (`Contributions#contribute_check`), keyed by its contributed name and
393
+ # non-critical unless the contributor said otherwise.
394
+ #
316
395
  # Note the database check registers as `:database`, not the class's own
317
396
  # `:active_record` default — every consumer renamed it, and dashboards key
318
397
  # on the name.
@@ -322,35 +401,47 @@ module StandardHealth
322
401
  # failing. A name that is already registered is also skipped, so calling
323
402
  # this after (or before) hand-registering one of them never duplicates it.
324
403
  #
325
- # Each keyword takes:
326
- # true — register with the defaults above (the default)
404
+ # Each keyword (a built-in key or a contributed check's name) takes:
405
+ # true — register with the defaults (the default)
327
406
  # false — don't register it
328
407
  # Hash — register with overrides: `name:`, `critical:`, `timeout:`,
329
408
  # plus any constructor options (see #register_check)
330
409
  #
331
410
  # c.register_default_checks solid_cache: false,
332
- # audit_retention: { critical: false, timeout: 1 }
411
+ # audit_retention: { critical: false, timeout: 1 },
412
+ # standard_id_migrations: { critical: true }
413
+ #
414
+ # An unknown keyword raises ArgumentError listing the known ones.
333
415
  #
334
416
  # @return [Array<Symbol>] names actually registered by this call
335
- def register_default_checks(database: true, solid_queue: true, solid_cache: true, audit_retention: true)
336
- requested = { database: database, solid_queue: solid_queue,
337
- solid_cache: solid_cache, audit_retention: audit_retention }
417
+ def register_default_checks(**settings)
418
+ table = default_check_table
419
+ settings = settings.transform_keys(&:to_sym)
420
+ unknown = settings.keys - table.keys
421
+ unless unknown.empty?
422
+ raise ArgumentError,
423
+ "unknown default check#{"s" if unknown.size > 1} #{unknown.map(&:inspect).join(", ")}; " \
424
+ "known: #{table.keys.join(", ")}. A check from another gem is known only once that gem " \
425
+ "has contributed it (when it is required)."
426
+ end
338
427
 
339
- requested.filter_map do |key, setting|
340
- next unless setting
428
+ @contributions.defaults_applied!
341
429
 
342
- overrides = setting.is_a?(Hash) ? setting.transform_keys(&:to_sym) : {}
343
- default = DEFAULT_CHECKS.fetch(key)
430
+ table.filter_map do |key, default|
431
+ setting = settings.fetch(key, true)
432
+ next unless setting
344
433
  next unless default[:available].call
345
434
 
435
+ overrides = setting.is_a?(Hash) ? setting.transform_keys(&:to_sym) : {}
346
436
  name = (overrides.delete(:name) || default[:name]).to_sym
347
437
  next if @checks.any? { |reg| reg.name == name }
348
438
 
349
439
  critical = overrides.key?(:critical) ? overrides.delete(:critical) : default[:critical]
350
- timeout = overrides.delete(:timeout)
351
- klass = overrides.delete(:klass) || Object.const_get(default[:klass])
440
+ timeout = overrides.key?(:timeout) ? overrides.delete(:timeout) : default[:timeout]
441
+ klass = overrides.delete(:klass) || default_check_class(default)
442
+ options = default.fetch(:options, {}).merge(overrides)
352
443
 
353
- register_check(name, klass, critical: critical, timeout: timeout, **overrides)
444
+ register_check(name, klass, critical: critical, timeout: timeout, **options)
354
445
  name
355
446
  end
356
447
  end
@@ -362,13 +453,14 @@ module StandardHealth
362
453
  #
363
454
  # c.register_aggregate_check :solid_cable, StandardHealth::Checks::SolidCable
364
455
  # c.register_aggregate_check :attestation_roots, "AttestationRootsCheck"
456
+ #
457
+ # Re-registering a name replaces it in place, as for #register_check.
365
458
  def register_aggregate_check(name, klass, critical: false, timeout: nil, **options)
366
459
  validate_check_options!(klass, options)
367
460
  registration = Registration.new(
368
461
  name: name.to_sym, klass: klass, critical: critical, timeout: timeout, options: options
369
462
  )
370
- @aggregate_checks << registration
371
- registration
463
+ upsert_registration(@aggregate_checks, registration)
372
464
  end
373
465
 
374
466
  DiagnosticsAssertion = Struct.new(:name, :callable)
@@ -388,8 +480,8 @@ module StandardHealth
388
480
  # (`:ok`, `:warn` or `:error`) plus any detail keys. `name:` is set by
389
481
  # the gem. It runs per request, on the authenticated tier only, never on
390
482
  # /alive, /ready or the aggregate. A raise, a non-Hash, or an unknown
391
- # status becomes an `:error` row (a raise is also reported to
392
- # `Rails.error` as handled). An `:error` row makes the endpoint's
483
+ # status becomes an `:error` row (a raise is also reported, to
484
+ # `error_reporter` or else `Rails.error` as handled). An `:error` row makes the endpoint's
393
485
  # `status` `incomplete`; `:warn` does not.
394
486
  #
395
487
  # Re-registering a name replaces it, so `configure` can safely re-run
@@ -440,6 +532,37 @@ module StandardHealth
440
532
 
441
533
  private
442
534
 
535
+ # DEFAULT_CHECKS plus contributed checks, keyed for register_default_checks.
536
+ # A contribution under a built-in key (only `audit_retention` is allowed,
537
+ # see Contributions::RESERVED_CHECK_NAMES) replaces that entry in place, so
538
+ # the check keeps its position and is never registered twice.
539
+ def default_check_table
540
+ @contributions.checks.each_with_object(DEFAULT_CHECKS.dup) do |check, table|
541
+ table[check.name] = {
542
+ name: check.name, critical: check.critical, timeout: check.timeout,
543
+ options: check.options, klass: check.klass, contributed: true,
544
+ available: -> { true }
545
+ }
546
+ end
547
+ end
548
+
549
+ # Built-in defaults resolve their class now, so its constructor options
550
+ # are validated at boot. A contributed class name stays a String and
551
+ # resolves when the check runs (see Registration#check_class): the
552
+ # contributing gem's constant may not be loadable yet.
553
+ def default_check_class(default)
554
+ return default[:klass] if default[:contributed]
555
+
556
+ Object.const_get(default[:klass])
557
+ end
558
+
559
+ # Replaces the registration with the same name in place, or appends.
560
+ def upsert_registration(registry, registration)
561
+ index = registry.index { |existing| existing.name == registration.name }
562
+ index ? registry[index] = registration : registry << registration
563
+ registration
564
+ end
565
+
443
566
  # Rejects option keys the check's constructor cannot accept. Only
444
567
  # inspects the signature — never instantiates — so a check with side
445
568
  # effects in `initialize` is not run at boot. A constructor taking
@@ -0,0 +1,206 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "standard_health/env_spec"
4
+
5
+ module StandardHealth
6
+ # Checks and env vars announced by OTHER gems, through a Rails load hook so
7
+ # neither side needs a gemspec dependency on the other:
8
+ #
9
+ # # in standard_id — no `require "standard_health"`
10
+ # ActiveSupport.on_load(:standard_health) do |health|
11
+ # health.contribute_check :standard_id_migrations, "StandardId::Checks::Migrations"
12
+ # health.contribute_env_vars "standard_id" do
13
+ # recommended :STANDARD_ID_OAUTH_SIGNING_KEY, description: "..."
14
+ # forbidden :STANDARD_ID_BYPASS_CODE, in: %w[production]
15
+ # end
16
+ # end
17
+ #
18
+ # standard_health runs `ActiveSupport.run_load_hooks(:standard_health, ...)`
19
+ # once, when it is required. Hooks registered before that run then; hooks
20
+ # registered after it run immediately. Either way the block receives a
21
+ # `Contributions::Facade` over this registry (an arity-0 block is
22
+ # instance_eval'd on it), so load order between the gems does not matter.
23
+ #
24
+ # The registry is a process-wide singleton (`StandardHealth.contributions`)
25
+ # kept apart from `Configuration`, because the hooks run once per process
26
+ # and `StandardHealth.reset_config!` (which app and gem specs call before
27
+ # every example) must not lose what they contributed.
28
+ #
29
+ # Contributor-facing API: `#contribute_check` and `#contribute_env_vars`,
30
+ # the only two methods the facade exposes. The readers below them are how
31
+ # `Configuration` consumes the registry, and are not part of the public API.
32
+ class Contributions
33
+ # What `ActiveSupport.on_load(:standard_health)` yields: the two
34
+ # contributor methods and nothing else, so a contributing gem cannot come
35
+ # to depend on the registry's readers.
36
+ class Facade
37
+ def initialize(registry)
38
+ @registry = registry
39
+ end
40
+
41
+ # @see Contributions#contribute_check
42
+ def contribute_check(...)
43
+ @registry.contribute_check(...)
44
+ end
45
+
46
+ # @see Contributions#contribute_env_vars
47
+ def contribute_env_vars(...)
48
+ @registry.contribute_env_vars(...)
49
+ end
50
+ end
51
+
52
+ # A check another gem offers to `Configuration#register_default_checks`.
53
+ Check = Struct.new(:name, :klass, :critical, :timeout, :options, keyword_init: true)
54
+
55
+ # Names `register_default_checks` owns outright. A contribution may not
56
+ # take one: it would silently replace an app's database or queue gate.
57
+ # (`audit_retention` is deliberately absent — standard_audit is expected
58
+ # to contribute it and take over the hardcoded default.)
59
+ RESERVED_CHECK_NAMES = %i[database solid_queue solid_cache].freeze
60
+
61
+ def initialize
62
+ @checks = {}
63
+ @env_specs = {}
64
+ @defaults_applied = false
65
+ @shadow_warnings = Set.new
66
+ end
67
+
68
+ # @return [Facade] the object load hooks receive
69
+ def facade
70
+ @facade ||= Facade.new(self)
71
+ end
72
+
73
+ # Offer a check to every app that calls `register_default_checks`. It
74
+ # registers non-critical unless `critical: true`, and the app can still
75
+ # opt out or override it per name, exactly like a built-in default:
76
+ #
77
+ # c.register_default_checks standard_id_migrations: false
78
+ # c.register_default_checks standard_id_migrations: { critical: true }
79
+ #
80
+ # Pass `klass` as a String so the class is resolved when the check runs,
81
+ # not when the hook fires (the contributing gem's constants may not be
82
+ # loadable yet at that point). Same keywords as
83
+ # `Configuration#register_check`. Re-contributing a name replaces it.
84
+ #
85
+ # Contribute when the gem is required (top level of its main file or
86
+ # engine file). Under `Bundler.require` that is before any app
87
+ # initializer. A check contributed after the app has already called
88
+ # `register_default_checks` is NOT registered retroactively; a warning
89
+ # says so.
90
+ def contribute_check(name, klass, critical: false, timeout: nil, **options)
91
+ name = name.to_sym
92
+ if RESERVED_CHECK_NAMES.include?(name)
93
+ raise ArgumentError,
94
+ "#{name.inspect} is a standard_health default check and cannot be contributed; pick another name"
95
+ end
96
+ unless klass.is_a?(String) || klass.is_a?(Module)
97
+ raise ArgumentError, "contribute_check(#{name.inspect}) needs a class or a class name String; got #{klass.inspect}"
98
+ end
99
+
100
+ if @defaults_applied
101
+ warn "[standard_health] check #{name.inspect} was contributed after register_default_checks ran, " \
102
+ "so it is not registered. Contribute checks when the gem is required."
103
+ end
104
+
105
+ @checks[name] = Check.new(name: name, klass: klass, critical: critical, timeout: timeout, options: options)
106
+ end
107
+
108
+ # Declare env vars the contributing gem reads. The block is the
109
+ # `EnvSpec` DSL (`required` / `recommended` / `forbidden` / `group`), and
110
+ # every entry is grouped under `contributor` in the audit. The
111
+ # declarations join the app's `env_spec` on `/diagnostics/env` and in
112
+ # `Checks::EnvSpecAudit`; an entry the app declares itself (same name)
113
+ # wins over the gem's.
114
+ #
115
+ # `in:` takes plain environment names only (`in: %w[production]`).
116
+ # Mode aliases such as `:deployed` or `:live` belong to the app, so a
117
+ # Symbol `in:` or a `mode_alias` call raises `ArgumentError` here, when
118
+ # the contributing gem loads.
119
+ #
120
+ # A nested `group` inside the block is labelled under the contributor
121
+ # ("standard_singpass / MyInfo").
122
+ #
123
+ # If two contributors declare the same var, the one that contributed
124
+ # first wins and a warning names the var and both contributors (once per
125
+ # process). An app that declares the var itself overrides both, silently.
126
+ #
127
+ # Re-contributing under the same `contributor` replaces its declarations.
128
+ # Unlike checks, env vars are merged when the audit runs, so a late
129
+ # contribution still shows up.
130
+ def contribute_env_vars(contributor, &block)
131
+ raise ArgumentError, "contribute_env_vars(#{contributor.inspect}) needs a block" unless block
132
+
133
+ label = contributor.to_s
134
+ spec = EnvSpec.new
135
+ spec.group(label) { spec.instance_eval(&block) }
136
+ validate_plain_modes!(label, spec)
137
+ warn_shadowed_env_vars(label, spec)
138
+
139
+ @env_specs[label] = spec
140
+ end
141
+
142
+ # @api private
143
+ # @return [Array<Check>] in contribution order
144
+ def checks
145
+ @checks.values
146
+ end
147
+
148
+ # Every contributor's declarations as one spec, or nil when there are
149
+ # none. Each var appears once; if two gems declare it, the gem that
150
+ # contributed first wins.
151
+ #
152
+ # @api private
153
+ # @return [EnvSpec, nil]
154
+ def env_spec
155
+ @env_specs.values.reduce { |merged, spec| merged.reverse_merge(spec) }
156
+ end
157
+
158
+ # Called by `Configuration#register_default_checks`, so a check
159
+ # contributed after that point warns instead of silently not appearing.
160
+ #
161
+ # @api private
162
+ def defaults_applied!
163
+ @defaults_applied = true
164
+ end
165
+
166
+ private
167
+
168
+ # `env_spec` keeps the first contributor's entry for a var and drops the
169
+ # rest. Say so when the contribution happens, not on every audit, and
170
+ # only once per var and pair of contributors.
171
+ def warn_shadowed_env_vars(label, spec)
172
+ order = @env_specs.keys
173
+ order += [label] unless order.include?(label)
174
+ names = spec.entries.map(&:name)
175
+
176
+ @env_specs.each do |other_label, other|
177
+ next if other_label == label
178
+
179
+ first, second = [label, other_label].sort_by { |l| order.index(l) }
180
+ (other.entries.map(&:name) & names).each do |name|
181
+ next unless @shadow_warnings.add?([name, first, second])
182
+
183
+ warn "[standard_health] env var #{name} is contributed by both #{first.inspect} and " \
184
+ "#{second.inspect}; #{first.inspect} contributed first, so its declaration is used."
185
+ end
186
+ end
187
+ end
188
+
189
+ def validate_plain_modes!(label, spec)
190
+ unless spec.mode_aliases.empty?
191
+ raise ArgumentError,
192
+ "contribute_env_vars(#{label.inspect}) declares mode_alias " \
193
+ "#{spec.mode_aliases.keys.map(&:inspect).join(", ")}; mode aliases belong to the app, " \
194
+ "so use plain environment names (in: %w[production])"
195
+ end
196
+
197
+ aliased = spec.entries.select { |entry| entry.modes.is_a?(Symbol) }
198
+ return if aliased.empty?
199
+
200
+ raise ArgumentError,
201
+ "contribute_env_vars(#{label.inspect}) uses mode alias(es) in `in:` for " \
202
+ "#{aliased.map { |e| "#{e.name} (#{e.modes.inspect})" }.join(", ")}; mode aliases belong to " \
203
+ "the app, so use plain environment names (in: %w[production])"
204
+ end
205
+ end
206
+ end
@@ -21,7 +21,7 @@ module StandardHealth
21
21
  # order. Never raises: an assertion that raises, returns a non-Hash, or
22
22
  # returns an unknown status becomes an `:error` row.
23
23
  def run(config = StandardHealth.config)
24
- config.diagnostics_assertions.map { |assertion| evaluate(assertion) }
24
+ config.diagnostics_assertions.map { |assertion| evaluate(assertion, config) }
25
25
  end
26
26
 
27
27
  # True when any row is `:error`. `:warn` is advisory.
@@ -29,7 +29,7 @@ module StandardHealth
29
29
  Array(rows).any? { |row| row[:status] == :error }
30
30
  end
31
31
 
32
- def evaluate(assertion)
32
+ def evaluate(assertion, config)
33
33
  result = assertion.callable.call
34
34
  return invalid(assertion.name, "returned #{result.class}, expected a Hash") unless result.is_a?(Hash)
35
35
 
@@ -39,7 +39,7 @@ module StandardHealth
39
39
 
40
40
  { name: assertion.name }.merge(row.except(:name)).merge(status: status)
41
41
  rescue StandardError => e
42
- report(e, assertion.name)
42
+ report(e, assertion.name, config)
43
43
  # The doctor tier is authenticated, so the message is shown (the /ready
44
44
  # redaction rationale does not apply); the class is kept separately
45
45
  # for grouping.
@@ -50,10 +50,9 @@ module StandardHealth
50
50
  { name: name, status: :error, error: "diagnostics assertion #{name} #{detail}" }
51
51
  end
52
52
 
53
- def report(error, name)
54
- return unless defined?(::Rails) && ::Rails.respond_to?(:error) && ::Rails.error
55
-
56
- ::Rails.error.report(error, handled: true, severity: :warning,
53
+ # To `Configuration#error_reporter` when set, else `Rails.error`.
54
+ def report(error, name, config)
55
+ config.report_error(error, severity: :warning,
57
56
  context: { diagnostics_assertion: name }, source: "standard_health")
58
57
  rescue StandardError
59
58
  nil
@@ -42,7 +42,7 @@ module StandardHealth
42
42
  # time. When `unless:` returns truthy or `if:` returns falsy the entry
43
43
  # is reported with `status: :not_applicable`.
44
44
  # - `group` (String, optional) — set implicitly by enclosing `group`
45
- # block; surfaced verbatim.
45
+ # block(s), nested labels joined with " / "; surfaced verbatim.
46
46
  # - `deprecated:` (Boolean, optional) — flag for staged removal. When
47
47
  # true, the audit row includes `deprecated: true`.
48
48
  # - `sunset_on:` (String/Date, optional) — target removal date.
@@ -71,6 +71,9 @@ module StandardHealth
71
71
  # cannot drift apart on what counts as a violation.
72
72
  VIOLATION_STATUSES = %i[missing forbidden mismatch].freeze
73
73
 
74
+ # Joins the labels of nested `group` blocks.
75
+ GROUP_SEPARATOR = " / "
76
+
74
77
  # Internal entry record. `modes` may be an Array<String> or a Symbol
75
78
  # alias that gets resolved at audit time.
76
79
  Entry = Struct.new(
@@ -115,10 +118,46 @@ module StandardHealth
115
118
  @mode_aliases[name.to_sym] = Array(modes).map(&:to_s)
116
119
  end
117
120
 
121
+ # Resolves every `in:` alias now. `Configuration#env_spec=` calls this,
122
+ # so an undeclared or misspelt alias fails at boot instead of raising on
123
+ # the first audit (a /diagnostics/env request, or an EnvSpecAudit row).
124
+ #
125
+ # @raise [UnknownModeAlias] naming every unknown alias
126
+ # @return [self]
127
+ def validate!
128
+ unknown = entries.filter_map { |entry| entry.modes if alias_unknown?(entry.modes) }.uniq
129
+ return self if unknown.empty?
130
+
131
+ raise UnknownModeAlias,
132
+ "Unknown mode alias#{"es" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")} " \
133
+ "(declare it with mode_alias)"
134
+ end
135
+
136
+ # A new spec holding this spec's entries followed by `other`'s entries
137
+ # for every var this spec does not declare. This spec wins: if it
138
+ # declares a name at all, none of `other`'s entries for that name are
139
+ # kept. Mode aliases are combined the same way (this spec's win).
140
+ #
141
+ # This is how gem-contributed declarations join the app's spec (see
142
+ # `StandardHealth::Contributions#contribute_env_vars`). Neither receiver
143
+ # nor argument is modified.
144
+ #
145
+ # @param other [EnvSpec]
146
+ # @return [EnvSpec]
147
+ def reverse_merge(other)
148
+ declared = entries.map(&:name)
149
+
150
+ self.class.new.tap do |merged|
151
+ other.mode_aliases.merge(mode_aliases).each { |name, modes| merged.mode_alias(name, modes) }
152
+ merged.append_entries(entries + other.entries.reject { |entry| declared.include?(entry.name) })
153
+ end
154
+ end
155
+
118
156
  # Group subsequent declarations under a label. Pure metadata —
119
157
  # propagated to audit rows as `group:` and otherwise inert. Nested
120
- # `group` blocks are supported; the innermost label is the one that
121
- # propagates to enclosed entries.
158
+ # `group` blocks combine their labels outermost first, so
159
+ # `group("standard_singpass") { group("MyInfo") { ... } }` tags the
160
+ # enclosed entries "standard_singpass / MyInfo".
122
161
  #
123
162
  # @param label [String]
124
163
  def group(label, &block)
@@ -215,6 +254,12 @@ module StandardHealth
215
254
  end
216
255
  end
217
256
 
257
+ protected
258
+
259
+ def append_entries(new_entries)
260
+ @entries.concat(new_entries)
261
+ end
262
+
218
263
  private
219
264
 
220
265
  def add(level, name, **opts)
@@ -227,7 +272,7 @@ module StandardHealth
227
272
  consumed_by: normalize_consumed_by(opts[:consumed_by]),
228
273
  if_predicate: opts[:if],
229
274
  unless_predicate: opts[:unless],
230
- group: @group_stack.last,
275
+ group: (@group_stack.join(GROUP_SEPARATOR) unless @group_stack.empty?),
231
276
  deprecated: opts[:deprecated] ? true : nil,
232
277
  sunset_on: opts[:sunset_on],
233
278
  replacement: opts[:replacement],
@@ -253,6 +298,10 @@ module StandardHealth
253
298
  modes.include?(mode_str)
254
299
  end
255
300
 
301
+ def alias_unknown?(modes)
302
+ modes.is_a?(Symbol) && !@mode_aliases.key?(modes)
303
+ end
304
+
256
305
  def resolve_modes(modes)
257
306
  return nil if modes.nil?
258
307
  if modes.is_a?(Symbol)
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module StandardHealth
4
- VERSION = "0.7.1"
4
+ VERSION = "0.9.0"
5
5
  end
@@ -1,11 +1,13 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require "active_support/lazy_load_hooks"
3
4
  require "standard_health/version"
4
5
  require "standard_health/probe_paths"
5
6
  require "standard_health/engine"
6
7
  require "standard_health/diagnostics_basic_auth"
7
8
  require "standard_health/configuration"
8
9
  require "standard_health/env_spec"
10
+ require "standard_health/contributions"
9
11
  require "standard_health/check"
10
12
  require "standard_health/checks/active_record"
11
13
  require "standard_health/checks/solid_queue"
@@ -42,11 +44,25 @@ module StandardHealth
42
44
  end
43
45
 
44
46
  # Mostly useful in tests — wipes the singleton config so each example
45
- # gets a clean slate.
47
+ # gets a clean slate. Contributions from other gems are NOT wiped: they
48
+ # live in `contributions`, and the new config reads the same registry.
46
49
  def reset_config!
47
50
  @config = Configuration.new
48
51
  end
49
52
 
53
+ # Checks and env vars other gems contributed through
54
+ # `ActiveSupport.on_load(:standard_health)`. See `Contributions`.
55
+ # Process-wide and deliberately not reset by `reset_config!`: the hooks
56
+ # run once per process, so nothing would re-contribute.
57
+ #
58
+ # Contributing gems never see this registry, only its
59
+ # `Contributions::Facade`.
60
+ #
61
+ # @api private
62
+ def contributions
63
+ @contributions ||= Contributions.new
64
+ end
65
+
50
66
  # The subscriber registry. Wired at boot by the engine initializer; also
51
67
  # callable directly so a host can re-run `setup!` after changing config
52
68
  # at runtime (and so tests can tear subscriptions down between examples).
@@ -91,3 +107,9 @@ module StandardHealth
91
107
  end
92
108
  end
93
109
  end
110
+
111
+ # Hands the registry's contributor facade (`contribute_check` and
112
+ # `contribute_env_vars`, nothing else) to every
113
+ # `ActiveSupport.on_load(:standard_health)` hook: those already registered by
114
+ # gems required earlier run now, and any registered later run immediately.
115
+ ActiveSupport.run_load_hooks(:standard_health, StandardHealth.contributions.facade)
metadata CHANGED
@@ -1,10 +1,10 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: standard_health
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.7.1
4
+ version: 0.9.0
5
5
  platform: ruby
6
6
  authors:
7
- - Jaryl Sim
7
+ - Rarebit One
8
8
  bindir: bin
9
9
  cert_chain: []
10
10
  date: 1980-01-02 00:00:00.000000000 Z
@@ -54,6 +54,7 @@ files:
54
54
  - lib/standard_health/checks/solid_cache.rb
55
55
  - lib/standard_health/checks/solid_queue.rb
56
56
  - lib/standard_health/configuration.rb
57
+ - lib/standard_health/contributions.rb
57
58
  - lib/standard_health/diagnostics_assertions.rb
58
59
  - lib/standard_health/diagnostics_basic_auth.rb
59
60
  - lib/standard_health/engine.rb
@@ -88,7 +89,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
88
89
  - !ruby/object:Gem::Version
89
90
  version: '0'
90
91
  requirements: []
91
- rubygems_version: 4.0.10
92
+ rubygems_version: 4.0.20
92
93
  specification_version: 4
93
94
  summary: A drop-in health check and environment-spec engine for Rails 8 host apps.
94
95
  test_files: []