standard_health 0.8.0 → 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 +54 -0
- data/README.md +128 -5
- 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 +119 -16
- data/lib/standard_health/contributions.rb +206 -0
- data/lib/standard_health/diagnostics_assertions.rb +6 -7
- data/lib/standard_health/env_spec.rb +34 -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,60 @@ 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
|
+
|
|
10
64
|
## [0.8.0] - 2026-10-22
|
|
11
65
|
|
|
12
66
|
### Changed
|
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
|
|
|
@@ -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`,
|
|
@@ -554,6 +566,104 @@ c.register_check :runner, "RunnerHealthCheck"
|
|
|
554
566
|
|
|
555
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`.
|
|
556
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
|
+
|
|
557
667
|
## Opt-in checks
|
|
558
668
|
|
|
559
669
|
Every check in this gem must be registered explicitly; **none are registered
|
|
@@ -888,6 +998,19 @@ probe period means ~6 evaluations/minute/instance:
|
|
|
888
998
|
The Logger also reports `aggregate.evaluated` (silent on ok); Sentry and
|
|
889
999
|
Metrics ignore it.
|
|
890
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
|
+
|
|
891
1014
|
### Narrowing metrics (0.6.0)
|
|
892
1015
|
|
|
893
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,
|
|
@@ -97,6 +97,27 @@ module StandardHealth
|
|
|
97
97
|
@env_spec = spec
|
|
98
98
|
end
|
|
99
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
|
|
120
|
+
|
|
100
121
|
# --- Instrumentation -----------------------------------------------
|
|
101
122
|
#
|
|
102
123
|
# Master switch for the Logger / Sentry / Metrics subscribers. On by
|
|
@@ -168,6 +189,37 @@ module StandardHealth
|
|
|
168
189
|
# Extra `call(event_name, payload)` subscribers supplied by the host.
|
|
169
190
|
attr_reader :extra_notifiers
|
|
170
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
|
+
|
|
171
223
|
# --- Response redaction --------------------------------------------
|
|
172
224
|
#
|
|
173
225
|
# When false (the default) a failing check reports `error_class` +
|
|
@@ -224,7 +276,10 @@ module StandardHealth
|
|
|
224
276
|
# one — or better, a driver-level timeout.
|
|
225
277
|
attr_accessor :total_check_budget
|
|
226
278
|
|
|
227
|
-
|
|
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
|
|
228
283
|
@parent_controller = "ActionController::API"
|
|
229
284
|
@diagnostics_parent_controller = nil
|
|
230
285
|
@diagnostics_basic_auth = nil
|
|
@@ -243,6 +298,7 @@ module StandardHealth
|
|
|
243
298
|
@metrics_enabled = true
|
|
244
299
|
@metric_events = nil
|
|
245
300
|
@extra_notifiers = []
|
|
301
|
+
@error_reporter = nil
|
|
246
302
|
|
|
247
303
|
@expose_check_errors = false
|
|
248
304
|
@detail_token = nil
|
|
@@ -295,6 +351,9 @@ module StandardHealth
|
|
|
295
351
|
# registration name, criticality, the check class (a String, resolved only
|
|
296
352
|
# if the backing library is loaded), and the guard that decides whether
|
|
297
353
|
# the backing library is present.
|
|
354
|
+
#
|
|
355
|
+
# Checks other gems contribute (`Contributions#contribute_check`) join this
|
|
356
|
+
# set at `register_default_checks` time.
|
|
298
357
|
DEFAULT_CHECKS = {
|
|
299
358
|
database: {
|
|
300
359
|
name: :database, critical: true,
|
|
@@ -311,6 +370,10 @@ module StandardHealth
|
|
|
311
370
|
klass: "StandardHealth::Checks::SolidCache",
|
|
312
371
|
available: -> { defined?(::SolidCache) }
|
|
313
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.
|
|
314
377
|
audit_retention: {
|
|
315
378
|
name: :audit_retention, critical: false,
|
|
316
379
|
klass: "StandardAudit::Checks::Retention",
|
|
@@ -325,6 +388,10 @@ module StandardHealth
|
|
|
325
388
|
# :solid_cache StandardHealth::Checks::SolidCache non-critical
|
|
326
389
|
# :audit_retention StandardAudit::Checks::Retention non-critical
|
|
327
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
|
+
#
|
|
328
395
|
# Note the database check registers as `:database`, not the class's own
|
|
329
396
|
# `:active_record` default — every consumer renamed it, and dashboards key
|
|
330
397
|
# on the name.
|
|
@@ -334,35 +401,47 @@ module StandardHealth
|
|
|
334
401
|
# failing. A name that is already registered is also skipped, so calling
|
|
335
402
|
# this after (or before) hand-registering one of them never duplicates it.
|
|
336
403
|
#
|
|
337
|
-
# Each keyword takes:
|
|
338
|
-
# 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)
|
|
339
406
|
# false — don't register it
|
|
340
407
|
# Hash — register with overrides: `name:`, `critical:`, `timeout:`,
|
|
341
408
|
# plus any constructor options (see #register_check)
|
|
342
409
|
#
|
|
343
410
|
# c.register_default_checks solid_cache: false,
|
|
344
|
-
# 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.
|
|
345
415
|
#
|
|
346
416
|
# @return [Array<Symbol>] names actually registered by this call
|
|
347
|
-
def register_default_checks(
|
|
348
|
-
|
|
349
|
-
|
|
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
|
|
350
427
|
|
|
351
|
-
|
|
352
|
-
next unless setting
|
|
428
|
+
@contributions.defaults_applied!
|
|
353
429
|
|
|
354
|
-
|
|
355
|
-
|
|
430
|
+
table.filter_map do |key, default|
|
|
431
|
+
setting = settings.fetch(key, true)
|
|
432
|
+
next unless setting
|
|
356
433
|
next unless default[:available].call
|
|
357
434
|
|
|
435
|
+
overrides = setting.is_a?(Hash) ? setting.transform_keys(&:to_sym) : {}
|
|
358
436
|
name = (overrides.delete(:name) || default[:name]).to_sym
|
|
359
437
|
next if @checks.any? { |reg| reg.name == name }
|
|
360
438
|
|
|
361
439
|
critical = overrides.key?(:critical) ? overrides.delete(:critical) : default[:critical]
|
|
362
|
-
timeout = overrides.delete(:timeout)
|
|
363
|
-
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)
|
|
364
443
|
|
|
365
|
-
register_check(name, klass, critical: critical, timeout: timeout, **
|
|
444
|
+
register_check(name, klass, critical: critical, timeout: timeout, **options)
|
|
366
445
|
name
|
|
367
446
|
end
|
|
368
447
|
end
|
|
@@ -401,8 +480,8 @@ module StandardHealth
|
|
|
401
480
|
# (`:ok`, `:warn` or `:error`) plus any detail keys. `name:` is set by
|
|
402
481
|
# the gem. It runs per request, on the authenticated tier only, never on
|
|
403
482
|
# /alive, /ready or the aggregate. A raise, a non-Hash, or an unknown
|
|
404
|
-
# status becomes an `:error` row (a raise is also reported to
|
|
405
|
-
# `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
|
|
406
485
|
# `status` `incomplete`; `:warn` does not.
|
|
407
486
|
#
|
|
408
487
|
# Re-registering a name replaces it, so `configure` can safely re-run
|
|
@@ -453,6 +532,30 @@ module StandardHealth
|
|
|
453
532
|
|
|
454
533
|
private
|
|
455
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
|
+
|
|
456
559
|
# Replaces the registration with the same name in place, or appends.
|
|
457
560
|
def upsert_registration(registry, registration)
|
|
458
561
|
index = registry.index { |existing| existing.name == registration.name }
|
|
@@ -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(
|
|
@@ -130,10 +133,31 @@ module StandardHealth
|
|
|
130
133
|
"(declare it with mode_alias)"
|
|
131
134
|
end
|
|
132
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
|
+
|
|
133
156
|
# Group subsequent declarations under a label. Pure metadata —
|
|
134
157
|
# propagated to audit rows as `group:` and otherwise inert. Nested
|
|
135
|
-
# `group` blocks
|
|
136
|
-
#
|
|
158
|
+
# `group` blocks combine their labels outermost first, so
|
|
159
|
+
# `group("standard_singpass") { group("MyInfo") { ... } }` tags the
|
|
160
|
+
# enclosed entries "standard_singpass / MyInfo".
|
|
137
161
|
#
|
|
138
162
|
# @param label [String]
|
|
139
163
|
def group(label, &block)
|
|
@@ -230,6 +254,12 @@ module StandardHealth
|
|
|
230
254
|
end
|
|
231
255
|
end
|
|
232
256
|
|
|
257
|
+
protected
|
|
258
|
+
|
|
259
|
+
def append_entries(new_entries)
|
|
260
|
+
@entries.concat(new_entries)
|
|
261
|
+
end
|
|
262
|
+
|
|
233
263
|
private
|
|
234
264
|
|
|
235
265
|
def add(level, name, **opts)
|
|
@@ -242,7 +272,7 @@ module StandardHealth
|
|
|
242
272
|
consumed_by: normalize_consumed_by(opts[:consumed_by]),
|
|
243
273
|
if_predicate: opts[:if],
|
|
244
274
|
unless_predicate: opts[:unless],
|
|
245
|
-
group: @group_stack.
|
|
275
|
+
group: (@group_stack.join(GROUP_SEPARATOR) unless @group_stack.empty?),
|
|
246
276
|
deprecated: opts[:deprecated] ? true : nil,
|
|
247
277
|
sunset_on: opts[:sunset_on],
|
|
248
278
|
replacement: opts[:replacement],
|
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: []
|