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 +4 -4
- data/CHANGELOG.md +31 -0
- data/README.md +39 -9
- data/lib/standard_audit/checks/retention.rb +2 -1
- data/lib/standard_audit/checks/schema.rb +2 -1
- data/lib/standard_audit/configuration.rb +24 -5
- data/lib/standard_audit/health_contributions.rb +23 -0
- data/lib/standard_audit/operation.rb +4 -3
- data/lib/standard_audit/version.rb +1 -1
- data/lib/standard_audit.rb +1 -0
- 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: 1b9c061fdc60d6b6d86ad40cb21da74510ddaa6a8a2105e48ea4acafb11ed893
|
|
4
|
+
data.tar.gz: 7cfece84130b3f5da19dc698ef65f64752459bf07b6af129ae1bcc7a6a10095b
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
-
|
|
397
|
-
|
|
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.
|
|
629
|
-
#
|
|
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.
|
|
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,
|
|
1167
|
-
`StandardAudit::Checks::Schema`
|
|
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
|
-
#
|
|
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.
|
|
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.
|
|
176
|
-
# the DSL is adoptable before an app has a
|
|
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 =
|
|
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
|
-
|
|
333
|
-
|
|
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.
|
|
61
|
-
#
|
|
62
|
-
#
|
|
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
|
data/lib/standard_audit.rb
CHANGED
|
@@ -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.
|
|
4
|
+
version: 0.16.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
|
|
@@ -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.
|
|
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: []
|