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 +4 -4
- data/CHANGELOG.md +70 -0
- data/README.md +133 -6
- data/app/controllers/standard_health/diagnostics_controller.rb +4 -3
- data/lib/generators/standard_health/install/templates/initializer.rb.erb +2 -1
- data/lib/standard_health/aggregator.rb +3 -3
- data/lib/standard_health/checks/env_spec_audit.rb +2 -1
- data/lib/standard_health/configuration.rb +144 -21
- data/lib/standard_health/contributions.rb +206 -0
- data/lib/standard_health/diagnostics_assertions.rb +6 -7
- data/lib/standard_health/env_spec.rb +53 -4
- data/lib/standard_health/version.rb +1 -1
- data/lib/standard_health.rb +23 -1
- metadata +4 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: e40d17a77554d7b4f1501fbd1e0d976d7a7d3787a3955f46b708dea9b92a8c97
|
|
4
|
+
data.tar.gz: a75f0a49175b3be0122203dd996695b7b2348d44005f42e123ba2faa4e2ca0f7
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
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
|
|
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
|
|
469
|
-
the
|
|
470
|
-
|
|
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
|
|
21
|
-
#
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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(
|
|
336
|
-
|
|
337
|
-
|
|
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
|
-
|
|
340
|
-
next unless setting
|
|
428
|
+
@contributions.defaults_applied!
|
|
341
429
|
|
|
342
|
-
|
|
343
|
-
|
|
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) ||
|
|
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, **
|
|
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
|
|
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
|
-
|
|
54
|
-
|
|
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
|
|
121
|
-
#
|
|
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.
|
|
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)
|
data/lib/standard_health.rb
CHANGED
|
@@ -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.
|
|
4
|
+
version: 0.9.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
|
-
-
|
|
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.
|
|
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: []
|