paper_trail_diff 0.14.0 → 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 +501 -0
- data/QUICKSTART.md +21 -4
- data/README.md +59 -56
- data/docs/architecture.md +32 -11
- data/docs/performance.md +125 -391
- data/docs/reference.md +470 -117
- data/docs/testing.md +83 -7
- data/lib/paper_trail_diff/activity_boundary.rb +83 -26
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
- data/lib/paper_trail_diff/activity_event.rb +41 -10
- data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
- data/lib/paper_trail_diff/activity_history.rb +34 -9
- data/lib/paper_trail_diff/activity_range.rb +18 -3
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
- data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
- data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
- data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
- data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
- data/lib/paper_trail_diff/activity_view.rb +69 -0
- data/lib/paper_trail_diff/analysis.rb +37 -6
- data/lib/paper_trail_diff/analysis_batch.rb +25 -31
- data/lib/paper_trail_diff/approximate_paths.rb +48 -0
- data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
- data/lib/paper_trail_diff/association_discovery.rb +9 -1
- data/lib/paper_trail_diff/association_key.rb +56 -0
- data/lib/paper_trail_diff/association_traversal.rb +13 -4
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
- data/lib/paper_trail_diff/batch_preload.rb +53 -0
- data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
- data/lib/paper_trail_diff/change_row.rb +133 -0
- data/lib/paper_trail_diff/collection_comparator.rb +5 -32
- data/lib/paper_trail_diff/configuration.rb +35 -12
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
- data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
- data/lib/paper_trail_diff/deprecation.rb +61 -0
- data/lib/paper_trail_diff/diagnostics.rb +86 -99
- data/lib/paper_trail_diff/endpoint.rb +26 -3
- data/lib/paper_trail_diff/errors.rb +3 -1
- data/lib/paper_trail_diff/fallback_paths.rb +38 -0
- data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
- data/lib/paper_trail_diff/historical_filter.rb +19 -10
- data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
- data/lib/paper_trail_diff/nested_comparator.rb +19 -18
- data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
- data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
- data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
- data/lib/paper_trail_diff/prepared_history.rb +15 -1
- data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
- data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
- data/lib/paper_trail_diff/read_snapshot.rb +77 -0
- data/lib/paper_trail_diff/root_version_selection.rb +4 -2
- data/lib/paper_trail_diff/scope_condition.rb +157 -32
- data/lib/paper_trail_diff/scope_ranking.rb +23 -14
- data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
- data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
- data/lib/paper_trail_diff/snapshot.rb +16 -1
- data/lib/paper_trail_diff/support.rb +29 -2
- data/lib/paper_trail_diff/time_range.rb +39 -16
- data/lib/paper_trail_diff/timeline_builder.rb +13 -7
- data/lib/paper_trail_diff/timeline_range.rb +9 -1
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
- data/lib/paper_trail_diff/transaction_cut.rb +240 -0
- data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_boundary.rb +41 -10
- data/lib/paper_trail_diff/version_query.rb +34 -10
- data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
- data/lib/paper_trail_diff/version_table.rb +60 -0
- data/lib/paper_trail_diff.rb +101 -57
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
- data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
- data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
- data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
- data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
- data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
- data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
- data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
- data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
- data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
- data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
- data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
- data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
- data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
- data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
- data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
- data/sig/generated/paper_trail_diff/errors.rbs +3 -1
- data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
- data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
- data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
- data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
- data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
- data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
- data/sig/generated/paper_trail_diff/support.rbs +15 -0
- data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
- data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
- data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
- data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
- data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
- data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
- data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
- data/sig/generated/paper_trail_diff.rbs +29 -26
- metadata +49 -11
- data/lib/paper_trail_diff/activity_grouping.rb +0 -38
- data/lib/paper_trail_diff/batch_safety.rb +0 -63
- data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
- data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
- data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
- data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
# rbs_inline: enabled
|
|
3
|
+
|
|
4
|
+
module PaperTrailDiff
|
|
5
|
+
# Warns about options that do nothing any more and will be removed. In a
|
|
6
|
+
# Rails app, register the deprecator to configure it with the app's own:
|
|
7
|
+
#
|
|
8
|
+
# Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator
|
|
9
|
+
module Deprecation
|
|
10
|
+
CLOSE_ON = 'close_on: is deprecated and has no effect: a window already closes on the ' \
|
|
11
|
+
'current record when nothing on its requested paths was recorded after it. ' \
|
|
12
|
+
'Remove the option.'
|
|
13
|
+
ALLOW_EXPENSIVE = 'allow_expensive: is deprecated and has no effect: allow_approximate: true ' \
|
|
14
|
+
'alone accepts a path read with PT-AT, in batch methods too. Remove the ' \
|
|
15
|
+
'option.'
|
|
16
|
+
RELOAD_LIVE_ENDPOINTS = 'reload_live_endpoints: is deprecated and will be removed: skipping ' \
|
|
17
|
+
'the reload saves a query for the records and one per association ' \
|
|
18
|
+
'level, and reads values that may be stale. Remove the option.'
|
|
19
|
+
|
|
20
|
+
# Required when first used, as the library loads nothing it does not need.
|
|
21
|
+
#: () -> untyped
|
|
22
|
+
def self.deprecator
|
|
23
|
+
@deprecator ||= begin
|
|
24
|
+
require 'active_support/deprecation'
|
|
25
|
+
active_support = Object.const_get(:ActiveSupport) #: untyped
|
|
26
|
+
active_support.const_get(:Deprecation).new('a future release', 'paper_trail_diff')
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
# The one value close_on: took. It named what ends a wall-clock window,
|
|
31
|
+
# so it was meaningless without one, and until it is removed it is still
|
|
32
|
+
# checked as it was.
|
|
33
|
+
CLOSE_ON_CURRENT = :current
|
|
34
|
+
|
|
35
|
+
#: (Symbol?, untyped) -> void
|
|
36
|
+
def self.close_on!(close_on, within)
|
|
37
|
+
return if close_on.nil?
|
|
38
|
+
unless close_on == CLOSE_ON_CURRENT
|
|
39
|
+
raise ConfigurationError, "close_on: must be #{CLOSE_ON_CURRENT.inspect} or nil"
|
|
40
|
+
end
|
|
41
|
+
raise ConfigurationError, 'close_on: requires `within`' if within.nil?
|
|
42
|
+
|
|
43
|
+
deprecator.warn(CLOSE_ON)
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
#: (untyped) -> void
|
|
47
|
+
def self.allow_expensive!(allow_expensive)
|
|
48
|
+
deprecator.warn(ALLOW_EXPENSIVE) unless allow_expensive.nil?
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
# The value to use: the option still works until it is removed, and nil
|
|
52
|
+
# stands for its old default.
|
|
53
|
+
#: (untyped) -> untyped
|
|
54
|
+
def self.reload_live_endpoints!(reload)
|
|
55
|
+
return true if reload.nil?
|
|
56
|
+
|
|
57
|
+
deprecator.warn(RELOAD_LIVE_ENDPOINTS)
|
|
58
|
+
reload
|
|
59
|
+
end
|
|
60
|
+
end
|
|
61
|
+
end
|
|
@@ -64,65 +64,94 @@ module PaperTrailDiff
|
|
|
64
64
|
end
|
|
65
65
|
|
|
66
66
|
# Performs read-only checks for known PaperTrail/PT-AT reconstruction hazards.
|
|
67
|
+
#
|
|
68
|
+
# The endpoints are a comparison's: two versions, or a version and the
|
|
69
|
+
# current record, in either order. Two current records read no history, so
|
|
70
|
+
# nothing is checked.
|
|
67
71
|
class HistoryDiagnostics
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
+
STOPPING_CODES = %i[
|
|
73
|
+
unknown_association unsupported_association association_tracking_unavailable
|
|
74
|
+
].freeze
|
|
75
|
+
|
|
76
|
+
#: (untyped, untyped, associations: association_option, ?allow_approximate: bool) -> void
|
|
77
|
+
def initialize(from, to, associations:, allow_approximate: false)
|
|
78
|
+
@versions = validated_versions(from, to)
|
|
72
79
|
@tree = AssociationTree.build(associations)
|
|
80
|
+
@traversal = AssociationTraversal.new(@tree)
|
|
81
|
+
@preparer = TraversalPreparer.new(tree: @tree, traversal: @traversal,
|
|
82
|
+
allow_approximate: allow_approximate)
|
|
83
|
+
@allow_approximate = allow_approximate
|
|
73
84
|
@issues = [] #: Array[DiagnosticIssue]
|
|
74
85
|
end
|
|
75
86
|
|
|
76
87
|
#: () -> DiagnosticReport
|
|
77
88
|
def call
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
return DiagnosticReport.new(issues: @issues)
|
|
89
|
+
unless @versions.empty?
|
|
90
|
+
model_class = Endpoint.model_class(@versions.fetch(0))
|
|
91
|
+
ReadSnapshot.call([model_class]) do
|
|
92
|
+
# Runs whether or not associations are selected: unorderable versions
|
|
93
|
+
# corrupt a scalar timeline just as surely, and a report that inspected
|
|
94
|
+
# nothing has no business answering `ok?`.
|
|
95
|
+
inspect_version_sequence(model_class)
|
|
96
|
+
inspect_associations(model_class) unless @tree.empty?
|
|
97
|
+
end
|
|
88
98
|
end
|
|
89
|
-
|
|
90
|
-
traversal = AssociationTraversal.new(@tree)
|
|
91
|
-
selected = traversal.selected_reflections(model_class)
|
|
92
|
-
inspect_targets(selected)
|
|
93
|
-
inspect_checkpoint_timestamp(model_class)
|
|
94
|
-
inspect_habtm(model_class, selected)
|
|
95
99
|
DiagnosticReport.new(issues: @issues)
|
|
96
100
|
end
|
|
97
101
|
|
|
98
102
|
private
|
|
99
103
|
|
|
100
|
-
#
|
|
101
|
-
#
|
|
104
|
+
# Each refusal a comparison would raise is an error, so `ok?` is false
|
|
105
|
+
# exactly when one would. The checks after them read reflections that must
|
|
106
|
+
# resolve and PT-AT records that must be there.
|
|
107
|
+
#: (untyped) -> void
|
|
108
|
+
def inspect_associations(model_class)
|
|
109
|
+
refusals = @preparer.refusals(model_class, historical: true)
|
|
110
|
+
refusals.each { |refusal| add_error(refusal.code, refusal.message, refusal.path) }
|
|
111
|
+
return if refusals.any? { |refusal| STOPPING_CODES.include?(refusal.code) }
|
|
112
|
+
|
|
113
|
+
selected = @traversal.selected_reflections(model_class)
|
|
114
|
+
inspect_polymorphic_targets(selected)
|
|
115
|
+
inspect_approximate_paths(model_class) if @allow_approximate
|
|
116
|
+
inspect_checkpoint_timestamp(model_class)
|
|
117
|
+
inspect_habtm(model_class, selected)
|
|
118
|
+
end
|
|
119
|
+
|
|
120
|
+
# @rbs @versions: Array[untyped]
|
|
102
121
|
# @rbs @tree: AssociationTree
|
|
122
|
+
# @rbs @traversal: AssociationTraversal
|
|
123
|
+
# @rbs @preparer: TraversalPreparer
|
|
124
|
+
# @rbs @allow_approximate: bool
|
|
103
125
|
# @rbs @issues: Array[DiagnosticIssue]
|
|
104
126
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
127
|
+
# The endpoints that are versions, in the order given.
|
|
128
|
+
#: (untyped, untyped) -> Array[untyped]
|
|
129
|
+
def validated_versions(from, to)
|
|
130
|
+
Endpoint.validate!(from)
|
|
131
|
+
Endpoint.validate!(to)
|
|
132
|
+
unless Endpoint.identity(from) == Endpoint.identity(to)
|
|
133
|
+
raise VersionMismatchError, 'endpoints must belong to the same PaperTrail item'
|
|
109
134
|
end
|
|
110
135
|
|
|
111
|
-
|
|
112
|
-
rescue NoMethodError => e
|
|
113
|
-
raise VersionMismatchError, 'expected PaperTrail version endpoints', cause: e
|
|
136
|
+
[from, to].select { |endpoint| Endpoint.version?(endpoint) }
|
|
114
137
|
end
|
|
115
138
|
|
|
116
139
|
#: (Array[Array[untyped]]) -> void
|
|
117
|
-
def
|
|
140
|
+
def inspect_polymorphic_targets(selected)
|
|
118
141
|
selected.each do |path, reflection|
|
|
119
|
-
|
|
120
|
-
add_warning(:polymorphic_target_unverified, 'polymorphic target cannot be verified', path)
|
|
121
|
-
next
|
|
122
|
-
end
|
|
142
|
+
next unless reflection.polymorphic?
|
|
123
143
|
|
|
124
|
-
|
|
125
|
-
|
|
144
|
+
add_warning(:polymorphic_target_unverified, 'polymorphic target cannot be verified', path)
|
|
145
|
+
end
|
|
146
|
+
end
|
|
147
|
+
|
|
148
|
+
# Accepted, but read the way `allow_approximate:` describes.
|
|
149
|
+
#: (untyped) -> void
|
|
150
|
+
def inspect_approximate_paths(model_class)
|
|
151
|
+
ApproximatePaths.call(@traversal, model_class).each do |path, reason|
|
|
152
|
+
add_warning(:approximate_association,
|
|
153
|
+
"association #{path} is read approximately with PT-AT (#{reason}): a " \
|
|
154
|
+
'record that entered or left it since is reported wrongly', path)
|
|
126
155
|
end
|
|
127
156
|
end
|
|
128
157
|
|
|
@@ -139,9 +168,7 @@ module PaperTrailDiff
|
|
|
139
168
|
# transaction that more than one owner recorded members in cannot be read.
|
|
140
169
|
#: (untyped, Array[Array[untyped]]) -> void
|
|
141
170
|
def inspect_shared_transactions(model_class, habtm)
|
|
142
|
-
versions =
|
|
143
|
-
version.respond_to?(:transaction_id) && version.transaction_id
|
|
144
|
-
end
|
|
171
|
+
versions = @versions.select { |version| VersionBoundary.transaction_id(version) }
|
|
145
172
|
habtm.each do |path, reflection|
|
|
146
173
|
owners = HabtmTransactionOwners.new(model_class, reflection)
|
|
147
174
|
versions.each do |version|
|
|
@@ -154,15 +181,29 @@ module PaperTrailDiff
|
|
|
154
181
|
end
|
|
155
182
|
end
|
|
156
183
|
|
|
157
|
-
|
|
158
|
-
|
|
184
|
+
# With the current record as one endpoint there is one version, and the
|
|
185
|
+
# sequence runs on from it.
|
|
186
|
+
#: (untyped) -> void
|
|
187
|
+
def inspect_version_sequence(model_class)
|
|
188
|
+
first, last = @versions
|
|
159
189
|
@issues.concat(
|
|
160
|
-
VersionSequenceDiagnostics.new(
|
|
161
|
-
|
|
162
|
-
).call
|
|
190
|
+
VersionSequenceDiagnostics.new(first, last,
|
|
191
|
+
fallback_selected: fallback_selected?(model_class)).call
|
|
163
192
|
)
|
|
164
193
|
end
|
|
165
194
|
|
|
195
|
+
# Only a path PT-AT reads can lose a change between tied versions, and a
|
|
196
|
+
# traversal that does not resolve reads nothing at all.
|
|
197
|
+
#: (untyped) -> bool
|
|
198
|
+
def fallback_selected?(model_class)
|
|
199
|
+
return false if @tree.empty?
|
|
200
|
+
|
|
201
|
+
refusals = @preparer.refusals(model_class, historical: true)
|
|
202
|
+
return false if refusals.any? { |refusal| STOPPING_CODES.include?(refusal.code) }
|
|
203
|
+
|
|
204
|
+
FallbackPaths.any?(@traversal, model_class, approximate: @allow_approximate)
|
|
205
|
+
end
|
|
206
|
+
|
|
166
207
|
#: (untyped) -> void
|
|
167
208
|
def inspect_checkpoint_timestamp(model_class)
|
|
168
209
|
return if synchronized_timestamp_disabled?(model_class)
|
|
@@ -173,7 +214,7 @@ module PaperTrailDiff
|
|
|
173
214
|
|
|
174
215
|
#: (Array[String]) -> void
|
|
175
216
|
def inspect_transaction_metadata(paths)
|
|
176
|
-
|
|
217
|
+
@versions.each do |version|
|
|
177
218
|
if !version.respond_to?(:transaction_id)
|
|
178
219
|
add_error(:transaction_id_column_missing, 'version has no transaction_id column')
|
|
179
220
|
elsif version.transaction_id.nil?
|
|
@@ -189,36 +230,6 @@ module PaperTrailDiff
|
|
|
189
230
|
end
|
|
190
231
|
end
|
|
191
232
|
|
|
192
|
-
#: (untyped, String) -> void
|
|
193
|
-
def inspect_versioned_model(model_class, path)
|
|
194
|
-
return if model_versioned?(model_class)
|
|
195
|
-
|
|
196
|
-
# An error rather than a warning: `ok?` must not stay true for a
|
|
197
|
-
# comparison that cannot work, and this one raises at runtime.
|
|
198
|
-
add_error(
|
|
199
|
-
:unversioned_association_target,
|
|
200
|
-
"#{model_class.name} does not appear to have PaperTrail enabled",
|
|
201
|
-
path
|
|
202
|
-
)
|
|
203
|
-
end
|
|
204
|
-
|
|
205
|
-
#: (untyped, String) -> void
|
|
206
|
-
def inspect_through_model(reflection, path)
|
|
207
|
-
model_class = reflection.through_reflection.klass
|
|
208
|
-
return if model_versioned?(model_class)
|
|
209
|
-
|
|
210
|
-
add_warning(
|
|
211
|
-
:unversioned_through_model,
|
|
212
|
-
"#{model_class.name} does not appear to have PaperTrail enabled",
|
|
213
|
-
path
|
|
214
|
-
)
|
|
215
|
-
end
|
|
216
|
-
|
|
217
|
-
#: (untyped) -> bool
|
|
218
|
-
def model_versioned?(model_class)
|
|
219
|
-
Support.versioned?(model_class)
|
|
220
|
-
end
|
|
221
|
-
|
|
222
233
|
#: (untyped) -> bool
|
|
223
234
|
def synchronized_timestamp_disabled?(model_class)
|
|
224
235
|
options = model_class.paper_trail_options
|
|
@@ -227,30 +238,6 @@ module PaperTrailDiff
|
|
|
227
238
|
false
|
|
228
239
|
end
|
|
229
240
|
|
|
230
|
-
#: () -> bool
|
|
231
|
-
def association_tracking_available?
|
|
232
|
-
paper_trail = Object.const_get(:PaperTrail) #: untyped
|
|
233
|
-
config = paper_trail.config #: untyped
|
|
234
|
-
!!(defined?(::PaperTrailAssociationTracking) &&
|
|
235
|
-
config.respond_to?(:track_associations?) && config.track_associations?)
|
|
236
|
-
end
|
|
237
|
-
|
|
238
|
-
#: (untyped) -> Array[String]
|
|
239
|
-
def version_identity(version)
|
|
240
|
-
[version.item_type.to_s, version.item_id.to_s]
|
|
241
|
-
end
|
|
242
|
-
|
|
243
|
-
#: (untyped) -> String
|
|
244
|
-
def version_type(version)
|
|
245
|
-
subtype = version.item_subtype if version.respond_to?(:item_subtype)
|
|
246
|
-
subtype.to_s.empty? ? version.item_type.to_s : subtype.to_s
|
|
247
|
-
end
|
|
248
|
-
|
|
249
|
-
#: () -> String
|
|
250
|
-
def tracking_unavailable_message
|
|
251
|
-
'association tracking must be loaded and enabled to diagnose associations'
|
|
252
|
-
end
|
|
253
|
-
|
|
254
241
|
#: (Symbol, String, ?String?, ?untyped) -> void
|
|
255
242
|
def add_error(code, message, path = nil, version_id = nil)
|
|
256
243
|
add_issue(:error, code, message, path, version_id)
|
|
@@ -47,6 +47,29 @@ module PaperTrailDiff
|
|
|
47
47
|
validate_record!(endpoint)
|
|
48
48
|
end
|
|
49
49
|
|
|
50
|
+
# The record a method reads the history of: a record, saved or destroyed,
|
|
51
|
+
# of a model PaperTrail versions.
|
|
52
|
+
#: (untyped) -> void
|
|
53
|
+
def validate_root!(record)
|
|
54
|
+
unless record?(record)
|
|
55
|
+
raise InvalidEndpointError, "expected a record, got #{described(record)}"
|
|
56
|
+
end
|
|
57
|
+
return if Support.versioned?(record.class)
|
|
58
|
+
|
|
59
|
+
raise InvalidEndpointError,
|
|
60
|
+
"#{record.class.name} is not versioned, so it has no history: add has_paper_trail to it"
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
# A relation is named rather than inspected, which would load it.
|
|
64
|
+
#: (untyped) -> String
|
|
65
|
+
def described(value)
|
|
66
|
+
return 'nil' if value.nil?
|
|
67
|
+
return "the class #{value.name}" if value.is_a?(Module)
|
|
68
|
+
|
|
69
|
+
value.class.name.to_s
|
|
70
|
+
end
|
|
71
|
+
private_class_method :described
|
|
72
|
+
|
|
50
73
|
#: (untyped) -> bool
|
|
51
74
|
def version?(endpoint)
|
|
52
75
|
endpoint.respond_to?(:reify) &&
|
|
@@ -82,11 +105,11 @@ module PaperTrailDiff
|
|
|
82
105
|
raise InvalidEndpointError, "cannot resolve endpoint model: #{model_type}", cause: e
|
|
83
106
|
end
|
|
84
107
|
|
|
85
|
-
#
|
|
86
|
-
#
|
|
108
|
+
# Every PaperTrail version of the record, whatever scope its versions
|
|
109
|
+
# association has.
|
|
87
110
|
#: (untyped) -> untyped
|
|
88
111
|
def versions(record)
|
|
89
|
-
|
|
112
|
+
VersionQuery.for_items(record.class, record.id)
|
|
90
113
|
rescue NoMethodError => e
|
|
91
114
|
message = 'record does not expose a PaperTrail version history'
|
|
92
115
|
raise InvalidTimelineRangeError, message, cause: e
|
|
@@ -42,7 +42,9 @@ module PaperTrailDiff
|
|
|
42
42
|
# Historical candidate loading exceeded its explicitly bounded work budget.
|
|
43
43
|
class FilterLimitExceededError < Error; end
|
|
44
44
|
|
|
45
|
-
#
|
|
45
|
+
# No longer raised: `allow_approximate: true` alone accepts the paths it
|
|
46
|
+
# refused. Kept until `allow_expensive:` is removed, so code that rescues it
|
|
47
|
+
# still loads.
|
|
46
48
|
class UnsupportedBatchPathError < ConfigurationError; end
|
|
47
49
|
|
|
48
50
|
# Raised when a requested ActiveRecord association does not exist.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
# rbs_inline: enabled
|
|
3
|
+
|
|
4
|
+
module PaperTrailDiff
|
|
5
|
+
# Whether a request may read a path with PT-AT's reifier rather than from
|
|
6
|
+
# loaded history. PT-AT places association changes by timestamp alone, so
|
|
7
|
+
# only such a path can miss a change between two versions that share one;
|
|
8
|
+
# loaded history orders those versions by id.
|
|
9
|
+
module FallbackPaths
|
|
10
|
+
# A path history reads only approximately counts when it is allowed: a
|
|
11
|
+
# request that does not allow it is refused before anything is read.
|
|
12
|
+
#: (AssociationTraversal, untyped, approximate: bool) -> bool
|
|
13
|
+
def self.any?(traversal, model, approximate:)
|
|
14
|
+
return true if approximate && !ApproximatePaths.call(traversal, model).empty?
|
|
15
|
+
|
|
16
|
+
traversal.selected_reflections(model).any? { |_path, reflection| per_record?(reflection) }
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
# Loaded history cannot index a composite foreign key, and a polymorphic
|
|
20
|
+
# belongs_to's target, with its default scope, is known only per record.
|
|
21
|
+
#: (untyped) -> bool
|
|
22
|
+
def self.per_record?(reflection)
|
|
23
|
+
composite_key?(reflection) || (reflection.belongs_to? && reflection.polymorphic?)
|
|
24
|
+
end
|
|
25
|
+
private_class_method :per_record?
|
|
26
|
+
|
|
27
|
+
#: (untyped) -> bool
|
|
28
|
+
def self.composite_key?(reflection)
|
|
29
|
+
return true if reflection.foreign_key.is_a?(Array)
|
|
30
|
+
return false unless reflection.through_reflection?
|
|
31
|
+
|
|
32
|
+
[reflection.through_reflection, reflection.source_reflection].any? do |part|
|
|
33
|
+
composite_key?(part)
|
|
34
|
+
end
|
|
35
|
+
end
|
|
36
|
+
private_class_method :composite_key?
|
|
37
|
+
end
|
|
38
|
+
end
|
|
@@ -6,10 +6,8 @@ module PaperTrailDiff
|
|
|
6
6
|
class HistoricalAssociationReifier
|
|
7
7
|
#: (untyped, ?habtm_version: untyped) -> void
|
|
8
8
|
def initialize(version, habtm_version: version)
|
|
9
|
-
@transaction_id =
|
|
10
|
-
|
|
11
|
-
@habtm_transaction_id = habtm_version.transaction_id
|
|
12
|
-
end
|
|
9
|
+
@transaction_id = VersionBoundary.transaction_id(version)
|
|
10
|
+
@habtm_transaction_id = VersionBoundary.transaction_id(habtm_version)
|
|
13
11
|
@version_at = version.created_at
|
|
14
12
|
# Keyed on record identity rather than `object_id`, which Ruby may reuse
|
|
15
13
|
# once an earlier record in the same pass has been collected.
|
|
@@ -24,8 +24,10 @@ module PaperTrailDiff
|
|
|
24
24
|
@state_loader = PreparedVersionStateLoader.new
|
|
25
25
|
end
|
|
26
26
|
|
|
27
|
-
|
|
28
|
-
|
|
27
|
+
# More matches than the limit raise, unless the caller does not count
|
|
28
|
+
# them: candidates it only lists, such as deleted roots.
|
|
29
|
+
#: (Array[String], ?counted: bool) -> Array[String]
|
|
30
|
+
def call(candidates, counted: true)
|
|
29
31
|
matched = [] #: Array[String]
|
|
30
32
|
candidates.each_slice(CANDIDATE_BATCH) do |slice|
|
|
31
33
|
versions = candidate_versions(slice)
|
|
@@ -34,7 +36,7 @@ module PaperTrailDiff
|
|
|
34
36
|
next unless held?(versions.fetch(id, []), closing[id])
|
|
35
37
|
|
|
36
38
|
matched << id
|
|
37
|
-
reject_root_limit! if matched.length > @limit
|
|
39
|
+
reject_root_limit! if counted && matched.length > @limit
|
|
38
40
|
end
|
|
39
41
|
end
|
|
40
42
|
matched
|
|
@@ -64,7 +66,17 @@ module PaperTrailDiff
|
|
|
64
66
|
"unknown historical attributes: #{unknown.join(', ')}"
|
|
65
67
|
end
|
|
66
68
|
|
|
67
|
-
|
|
69
|
+
attributes.to_h { |name, value| [name, cast(name, value)] }
|
|
70
|
+
end
|
|
71
|
+
|
|
72
|
+
# Expected and recorded values compare as the attribute casts them, as
|
|
73
|
+
# `where` reads its values: an enum's symbol names its stored value, and a
|
|
74
|
+
# `json` or `jsonb` version column, which PaperTrail does not cast, holds
|
|
75
|
+
# dates and times as strings. Casting also copies a mutable value, so the
|
|
76
|
+
# filter keeps its own.
|
|
77
|
+
#: (String, untyped) -> untyped
|
|
78
|
+
def cast(name, value)
|
|
79
|
+
@model.type_for_attribute(name).cast(value)
|
|
68
80
|
end
|
|
69
81
|
|
|
70
82
|
#: (untyped) -> Integer
|
|
@@ -76,8 +88,7 @@ module PaperTrailDiff
|
|
|
76
88
|
|
|
77
89
|
#: (Array[String]) -> Hash[String, Array[untyped]]
|
|
78
90
|
def candidate_versions(ids)
|
|
79
|
-
relation =
|
|
80
|
-
item_id: ids)
|
|
91
|
+
relation = VersionQuery.for_items(@model, ids)
|
|
81
92
|
range = @time_range
|
|
82
93
|
relation = range.scope(relation) if range
|
|
83
94
|
# One past the remaining budget is enough to know it was exceeded.
|
|
@@ -107,9 +118,7 @@ module PaperTrailDiff
|
|
|
107
118
|
range = @time_range
|
|
108
119
|
return {} unless range
|
|
109
120
|
|
|
110
|
-
|
|
111
|
-
item_id: ids)
|
|
112
|
-
trailing = range.first_trailing_versions(relation)
|
|
121
|
+
trailing = range.first_trailing_versions(VersionQuery.for_items(@model, ids))
|
|
113
122
|
account_versions!(trailing.length)
|
|
114
123
|
trailing
|
|
115
124
|
end
|
|
@@ -162,7 +171,7 @@ module PaperTrailDiff
|
|
|
162
171
|
"historical_filter: #{name} was not recorded in version #{version.id}"
|
|
163
172
|
end
|
|
164
173
|
|
|
165
|
-
state.attributes.fetch(name) == expected
|
|
174
|
+
cast(name, state.attributes.fetch(name)) == expected
|
|
166
175
|
end
|
|
167
176
|
end
|
|
168
177
|
|