standard_audit 0.15.2 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 0f28d1e0742cc3754f99b25e1242c69c70f72cbf781d2fc696b3be326fccd74c
4
- data.tar.gz: 06f1dfe7a30578b6f8df0d3a672996802963dcdf9c316af967042b5b8f02648b
3
+ metadata.gz: 1b9c061fdc60d6b6d86ad40cb21da74510ddaa6a8a2105e48ea4acafb11ed893
4
+ data.tar.gz: 7cfece84130b3f5da19dc698ef65f64752459bf07b6af129ae1bcc7a6a10095b
5
5
  SHA512:
6
- metadata.gz: 32f665b055842c67a00bb099f4919ae230b0f304f7c493a2ad4b783fa83540099fc7cf2b2259e0c7d08d71024a87af6707548110813062ee795e137b123fa73f
7
- data.tar.gz: 3a8a1dc2fc568ee1668eb1dcd06fdc00620cb33f202c6b535d955e2b826ca2df0cd08e5ce3f9a214dfdbe741dc1f0bbf6def9add32531d96dabf92b6db2212fe
6
+ metadata.gz: 6848a86ac9a96e2bd836894bacacf152eab1fda78edd1b8e5bfe619fbf81c62af58488f2dfa9c132991e0199dbf508be068fa1aee4f79901a238b492abd54147
7
+ data.tar.gz: 21a8bdef77f05e3713d3f3f523b422edf4451aa772ced21c7c8580daf35dc857ca5784233cac1614745a4d2957e26192de7bd9837076095a19f3c8bb97c6d74c
data/CHANGELOG.md CHANGED
@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.16.0] - 2026-11-23
11
+
12
+ ### Added
13
+ - **StandardHealth contributions.** When standard_health is loaded, the gem
14
+ contributes its two readiness checks through standard_health's
15
+ `:standard_health` load hook: `audit_retention`
16
+ (`StandardAudit::Checks::Retention`) and `audit_schema`
17
+ (`StandardAudit::Checks::Schema`), both non-critical. It also declares
18
+ `STANDARD_AUDIT_RETENTION_DAYS` (recommended on production, where the
19
+ retention advisory fires) in a `standard_audit` env-audit group; an app that
20
+ sets `config.retention_days` in code can ignore that row. Apps on
21
+ `register_default_checks` get them with no initializer line, and
22
+ `audit_retention` takes over standard_health's deprecated built-in entry of
23
+ the same name, so it registers once. There is still no dependency on
24
+ standard_health; without it the hook never runs.
25
+ - **`config.subscribe_to` takes several patterns in one call**
26
+ (`config.subscribe_to "auth.*", /\Abilling\./`, or a splatted list,
27
+ `config.subscribe_to(*patterns)`). The one-pattern form works as before; a
28
+ call with no pattern raises `ArgumentError`.
29
+
30
+ ### Changed
31
+ - **`config.audit_catalogue` defaults to the host's `AuditCatalogue::ACTIONS`**
32
+ when the app defines it, resolved per call so Zeitwerk reloading still works.
33
+ An app without `AuditCatalogue` (or whose `AuditCatalogue` has no `ACTIONS`)
34
+ resolves to nil exactly as before, so its membership check stays skipped. An
35
+ app that defines `AuditCatalogue::ACTIONS` but never set `audit_catalogue`
36
+ now gets the membership check: in local environments `audit!` raises
37
+ `DeclarationError` for an action missing from it, and the meta-spec's
38
+ catalogue examples stop being skipped. Set `config.audit_catalogue = nil` to
39
+ keep the old behaviour.
40
+
10
41
  ## [0.15.2] - 2026-10-30
11
42
 
12
43
  ### Fixed
data/README.md CHANGED
@@ -393,8 +393,12 @@ StandardAudit.configure(baseline: true) do |config|
393
393
  end
394
394
  ```
395
395
 
396
- `nil` (the default) skips the membership check entirely, so the DSL is adoptable
397
- before you have a catalogue. **Membership is the only rule** — there is no
396
+ You can usually skip that line: the default resolves `AuditCatalogue::ACTIONS`
397
+ on each call when your app defines it, the estate convention. Without an
398
+ `AuditCatalogue` (or one with no `ACTIONS`), the default resolves to nil, which
399
+ skips the membership check entirely, so the DSL is adoptable before you have a
400
+ catalogue. Set `config.audit_catalogue` to point somewhere else, or to `nil` to
401
+ switch the check off. **Membership is the only rule** — there is no
398
402
  dot-count, case, prefix, or namespace validation, because an action may
399
403
  legitimately carry a notification-bus namespace verbatim.
400
404
 
@@ -568,9 +572,9 @@ hooks) as well as data, and a per-example reset would otherwise drop it.
568
572
  StandardAudit.configure(baseline: true) do |config|
569
573
  # -- Subscriptions --
570
574
  # Subscribe to ActiveSupport::Notifications patterns.
571
- # Supports wildcards.
575
+ # Supports wildcards and Regexps; one call may take several patterns.
572
576
  config.subscribe_to "myapp.*"
573
- config.subscribe_to "auth.*"
577
+ config.subscribe_to "auth.*", /\Abilling\./
574
578
 
575
579
  # -- Extractors --
576
580
  # How to pull actor/target/scope from notification payloads.
@@ -625,8 +629,9 @@ StandardAudit.configure(baseline: true) do |config|
625
629
  config.before_checksum :backfill_scope # an AuditLog instance method
626
630
 
627
631
  # -- Operation audit contract (StandardAudit::Operation) --
628
- # Your action vocabulary, as a CALLABLE so Zeitwerk can reload it. nil (the
629
- # default) skips the membership check entirely.
632
+ # Your action vocabulary, as a CALLABLE so Zeitwerk can reload it. Defaults
633
+ # to AuditCatalogue::ACTIONS when your app defines it; a nil result skips the
634
+ # membership check entirely.
630
635
  config.audit_catalogue = -> { AuditCatalogue::ACTIONS }
631
636
 
632
637
  # Whether `audit!` verifies declarations before writing. Callable or boolean;
@@ -945,7 +950,12 @@ enabling a finite window is a deliberate decision.
945
950
 
946
951
  `StandardAudit::Checks::Retention` is a [StandardHealth](https://github.com/rarebit-one/standard_health)-compatible
947
952
  check that flags unbounded retention **on production deployments** as an
948
- advisory. Register it (non-critical) in `config/initializers/standard_health.rb`:
953
+ advisory. When standard_health is loaded, the gem contributes it (non-critical)
954
+ through standard_health's load hook, alongside `audit_schema` and the
955
+ `STANDARD_AUDIT_RETENTION_DAYS` env declaration (see
956
+ [StandardHealth contributions](#standardhealth-contributions)), so an app that
957
+ calls `c.register_default_checks` gets it with no extra line. To register it by
958
+ hand instead:
949
959
 
950
960
  ```ruby
951
961
  StandardHealth.configure do |c|
@@ -966,6 +976,24 @@ which is **still HTTP 200** — it surfaces the advisory in the readiness JSON
966
976
  without failing the probe or blocking a deploy. The check is duck-typed and has
967
977
  no hard dependency on `standard_health`.
968
978
 
979
+ ### StandardHealth contributions
980
+
981
+ standard_audit never depends on standard_health. When both are in the bundle,
982
+ it registers a `:standard_health` load hook (`lib/standard_audit/health_contributions.rb`)
983
+ that contributes:
984
+
985
+ | Kind | Name | Detail |
986
+ |------|------|--------|
987
+ | check | `audit_retention` | `StandardAudit::Checks::Retention`, non-critical. Takes over standard_health's deprecated built-in entry of the same name, so it registers once. |
988
+ | check | `audit_schema` | `StandardAudit::Checks::Schema`, non-critical. |
989
+ | env var | `STANDARD_AUDIT_RETENTION_DAYS` | Recommended on production, in the `standard_audit` group of the env audit: a positive integer of days, or `indefinite`. An app that sets `config.retention_days` in code can ignore the row. |
990
+
991
+ Contributed checks join the set `register_default_checks` registers. Opt out or
992
+ override by name: `c.register_default_checks audit_schema: false` or
993
+ `audit_retention: { critical: true }`. An app that registered either name
994
+ itself keeps its own registration. An env var the app's own `env_spec` declares
995
+ wins over the gem's row.
996
+
969
997
  ## Chain Integrity
970
998
 
971
999
  Every row carries a SHA-256 `checksum` over its own fields **and the digest of
@@ -1163,8 +1191,10 @@ every write with `StandardAudit::MissingUpgradeMigration`), or `false` (skip).
1163
1191
  On PostgreSQL with a large table, add `disable_ddl_transaction!` and
1164
1192
  `algorithm: :concurrently` to the generated `add_index` calls.
1165
1193
 
1166
- To surface the gap in `/health/ready` as well, register the non-critical
1167
- `StandardAudit::Checks::Schema` next to `Checks::Retention`:
1194
+ To surface the gap in `/health/ready` as well, use the non-critical
1195
+ `StandardAudit::Checks::Schema`. `register_default_checks` picks it up through
1196
+ the [StandardHealth contributions](#standardhealth-contributions); to register
1197
+ it by hand:
1168
1198
 
1169
1199
  ```ruby
1170
1200
  c.register_check :audit_schema, StandardAudit::Checks::Schema, critical: false
@@ -8,7 +8,8 @@ module StandardAudit
8
8
  # StandardHealth aggregator calls, so it loads even where standard_health
9
9
  # is absent.
10
10
  #
11
- # Register it (NON-critical) in config/initializers/standard_health.rb:
11
+ # lib/standard_audit/health_contributions.rb contributes it (NON-critical)
12
+ # to standard_health's register_default_checks. To register it by hand:
12
13
  #
13
14
  # c.register_check :audit_retention,
14
15
  # StandardAudit::Checks::Retention,
@@ -4,7 +4,8 @@ module StandardAudit
4
4
  # is missing an upgrade migration (see StandardAudit::SchemaCheck).
5
5
  #
6
6
  # Duck-typed like Checks::Retention: `#initialize(name:, critical:)` +
7
- # `#run`, with no dependency on standard_health. Register it NON-critical:
7
+ # `#run`, with no dependency on standard_health. Contributed NON-critical
8
+ # by lib/standard_audit/health_contributions.rb; to register it by hand:
8
9
  #
9
10
  # c.register_check :audit_schema,
10
11
  # StandardAudit::Checks::Schema,
@@ -3,6 +3,13 @@ module StandardAudit
3
3
  # `config.retention_days = :indefinite`: keep audit rows forever, on purpose.
4
4
  INDEFINITE_RETENTION = :indefinite
5
5
 
6
+ # The `audit_catalogue` default: the host's `AuditCatalogue::ACTIONS` when
7
+ # it defines one, nil otherwise. `const_defined?(:ACTIONS, false)` looks on
8
+ # AuditCatalogue only, so a stray top-level `ACTIONS` never counts.
9
+ DEFAULT_AUDIT_CATALOGUE = -> {
10
+ ::AuditCatalogue::ACTIONS if defined?(::AuditCatalogue) && ::AuditCatalogue.const_defined?(:ACTIONS, false)
11
+ }
12
+
6
13
  attr_accessor :async, :queue_name, :enabled,
7
14
  :actor_extractor, :target_extractor, :scope_extractor,
8
15
  :current_actor_resolver, :current_request_id_resolver,
@@ -172,11 +179,17 @@ module StandardAudit
172
179
  # config.audit_catalogue = -> { AuditCatalogue::ACTIONS }
173
180
  #
174
181
  # A plain Array is accepted when the vocabulary really is a frozen
175
- # literal. `nil` (the default) skips the membership check entirely, so
176
- # the DSL is adoptable before an app has a catalogue.
182
+ # literal. A callable returning nil (or a plain `nil`) skips the
183
+ # membership check entirely, so the DSL is adoptable before an app has a
184
+ # catalogue.
185
+ #
186
+ # The default follows the estate convention: a host that defines
187
+ # `AuditCatalogue::ACTIONS` gets it without configuring anything, and a
188
+ # host that doesn't gets nil, exactly as when the default was nil.
189
+ # Resolved per call, like a host-set callable, so Zeitwerk can reload it.
177
190
  #
178
191
  # Membership is the ONLY rule applied — see StandardAudit::Operation.
179
- @audit_catalogue = nil
192
+ @audit_catalogue = DEFAULT_AUDIT_CATALOGUE
180
193
 
181
194
  # Whether `audit!` verifies the declaration before writing. A callable
182
195
  # (or a plain boolean). Defaults to local environments only: in
@@ -329,8 +342,14 @@ module StandardAudit
329
342
  hook
330
343
  end
331
344
 
332
- def subscribe_to(pattern)
333
- @subscriptions << pattern
345
+ # Adds one or more patterns (String, glob or Regexp) to audit:
346
+ #
347
+ # config.subscribe_to "myapp.*"
348
+ # config.subscribe_to "auth.*", /\Abilling\./
349
+ def subscribe_to(*patterns)
350
+ raise ArgumentError, "subscribe_to needs at least one pattern" if patterns.empty?
351
+
352
+ @subscriptions.concat(patterns)
334
353
  end
335
354
 
336
355
  def subscriptions
@@ -0,0 +1,23 @@
1
+ # Offers the gem's readiness checks and env vars to standard_health without
2
+ # depending on it. The block runs only when standard_health is loaded (it
3
+ # fires `run_load_hooks(:standard_health, ...)`), whichever gem loads first;
4
+ # without standard_health it never runs. An app that calls
5
+ # `register_default_checks` then gets both checks, non-critical, and can opt
6
+ # out or override them by name (`audit_schema: false`).
7
+ #
8
+ # The names match each check's default `name:`. `audit_retention` is also the
9
+ # key of standard_health's own (deprecated) built-in entry, which this
10
+ # contribution takes over, so the check registers once either way.
11
+ ActiveSupport.on_load(:standard_health) do |health|
12
+ health.contribute_check :audit_retention, "StandardAudit::Checks::Retention", critical: false
13
+ health.contribute_check :audit_schema, "StandardAudit::Checks::Schema", critical: false
14
+
15
+ health.contribute_env_vars "standard_audit" do
16
+ recommended :STANDARD_AUDIT_RETENTION_DAYS, in: %w[production],
17
+ description: "Days to keep audit_logs rows before StandardAudit::CleanupJob deletes them: a positive " \
18
+ "integer, or `indefinite` to keep them forever as a deliberate decision. Unset keeps them " \
19
+ "forever undecided, which the audit_retention check warns about on production. Read by " \
20
+ "StandardAudit::Configuration.retention_days_from_env. An app that sets " \
21
+ "`config.retention_days` in its initializer overrides it and can ignore this row."
22
+ end
23
+ end
@@ -57,9 +57,10 @@ module StandardAudit
57
57
  # end
58
58
  #
59
59
  # A CALLABLE, because referencing an autoloadable constant eagerly from an
60
- # initializer pins the first-loaded copy and breaks Zeitwerk reloading. `nil`
61
- # (the default) means the catalogue check is skipped entirely, so the DSL is
62
- # adoptable before an app has a catalogue.
60
+ # initializer pins the first-loaded copy and breaks Zeitwerk reloading. The
61
+ # default is that callable already, resolving `AuditCatalogue::ACTIONS` when
62
+ # the host defines it and nil otherwise; a nil catalogue means the check is
63
+ # skipped entirely, so the DSL is adoptable before an app has a catalogue.
63
64
  #
64
65
  # Membership is the ONLY rule applied to an action string. There is
65
66
  # deliberately no dot-count, case, prefix, or namespace validation: one app's
@@ -1,3 +1,3 @@
1
1
  module StandardAudit
2
- VERSION = "0.15.2"
2
+ VERSION = "0.16.0"
3
3
  end
@@ -30,6 +30,7 @@ require "standard_audit/audit_scope"
30
30
  require "standard_audit/schema_check"
31
31
  require "standard_audit/checks/retention"
32
32
  require "standard_audit/checks/schema"
33
+ require "standard_audit/health_contributions"
33
34
  require "standard_audit/auth_failure"
34
35
 
35
36
  module StandardAudit
metadata CHANGED
@@ -1,10 +1,10 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: standard_audit
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.15.2
4
+ version: 0.16.0
5
5
  platform: ruby
6
6
  authors:
7
- - Jaryl Sim
7
+ - Rarebit One
8
8
  bindir: bin
9
9
  cert_chain: []
10
10
  date: 1980-01-02 00:00:00.000000000 Z
@@ -115,6 +115,7 @@ files:
115
115
  - lib/standard_audit/configuration.rb
116
116
  - lib/standard_audit/engine.rb
117
117
  - lib/standard_audit/event_subscriber.rb
118
+ - lib/standard_audit/health_contributions.rb
118
119
  - lib/standard_audit/metadata_filter.rb
119
120
  - lib/standard_audit/operation.rb
120
121
  - lib/standard_audit/operation/audit.rb
@@ -152,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
152
153
  - !ruby/object:Gem::Version
153
154
  version: '0'
154
155
  requirements: []
155
- rubygems_version: 4.0.10
156
+ rubygems_version: 4.0.20
156
157
  specification_version: 4
157
158
  summary: Database-backed audit logging for Rails via Rails.event and ActiveSupport::Notifications.
158
159
  test_files: []