paper_trail_diff 0.13.1 → 0.15.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 +630 -0
- data/QUICKSTART.md +30 -10
- data/README.md +91 -13
- data/docs/architecture.md +62 -18
- data/docs/performance.md +116 -298
- data/docs/reference.md +554 -102
- data/docs/testing.md +93 -14
- data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
- 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 +11 -1
- data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
- data/lib/paper_trail_diff/activity_event.rb +41 -10
- data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
- data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
- data/lib/paper_trail_diff/activity_history.rb +34 -9
- data/lib/paper_trail_diff/activity_range.rb +32 -5
- data/lib/paper_trail_diff/activity_relationship.rb +12 -0
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
- data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
- 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 +37 -24
- data/lib/paper_trail_diff/activity_view.rb +69 -0
- data/lib/paper_trail_diff/analysis.rb +13 -1
- data/lib/paper_trail_diff/analysis_batch.rb +24 -30
- data/lib/paper_trail_diff/approximate_paths.rb +48 -0
- data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
- data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
- data/lib/paper_trail_diff/association_discovery.rb +14 -11
- data/lib/paper_trail_diff/association_key.rb +56 -0
- data/lib/paper_trail_diff/association_traversal.rb +180 -47
- 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 +12 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
- 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/comparison_batch.rb +37 -10
- data/lib/paper_trail_diff/configuration.rb +35 -12
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
- data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
- data/lib/paper_trail_diff/deprecation.rb +61 -0
- data/lib/paper_trail_diff/diagnostics.rb +105 -102
- data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
- data/lib/paper_trail_diff/endpoint.rb +26 -3
- data/lib/paper_trail_diff/errors.rb +5 -2
- data/lib/paper_trail_diff/fallback_paths.rb +38 -0
- data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
- data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
- data/lib/paper_trail_diff/historical_filter.rb +19 -10
- data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
- data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
- data/lib/paper_trail_diff/nested_comparator.rb +19 -18
- data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
- data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
- data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
- data/lib/paper_trail_diff/prepared_history.rb +70 -53
- data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
- data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
- data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
- data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
- data/lib/paper_trail_diff/recorded_changes.rb +83 -0
- data/lib/paper_trail_diff/recorded_class.rb +53 -0
- data/lib/paper_trail_diff/root_version_selection.rb +4 -2
- data/lib/paper_trail_diff/scope_condition.rb +386 -0
- data/lib/paper_trail_diff/scope_ranking.rb +206 -0
- data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
- data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
- data/lib/paper_trail_diff/snapshot.rb +16 -1
- data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
- data/lib/paper_trail_diff/support.rb +38 -6
- data/lib/paper_trail_diff/time_range.rb +37 -18
- data/lib/paper_trail_diff/time_version_range.rb +5 -5
- data/lib/paper_trail_diff/timeline_builder.rb +7 -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 +181 -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_association_candidate_scope.rb +13 -3
- data/lib/paper_trail_diff/version_boundary.rb +37 -8
- data/lib/paper_trail_diff/version_query.rb +34 -10
- data/lib/paper_trail_diff/version_range.rb +8 -15
- data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
- data/lib/paper_trail_diff/version_table.rb +60 -0
- data/lib/paper_trail_diff.rb +126 -55
- data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
- data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
- data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
- data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
- data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
- data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
- data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
- data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
- data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
- 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_activity_edge.rbs +148 -0
- data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
- data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
- data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
- data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
- 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/comparison_batch.rbs +22 -4
- data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
- data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
- data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
- data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
- data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
- data/sig/generated/paper_trail_diff/errors.rbs +5 -2
- data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
- data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
- data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
- data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
- data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
- data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
- data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
- data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
- data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
- data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
- data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
- data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
- data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
- data/sig/generated/paper_trail_diff/support.rbs +20 -2
- data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
- data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -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 +94 -0
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
- data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
- data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
- data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
- data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
- data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
- data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
- data/sig/generated/paper_trail_diff.rbs +47 -25
- metadata +62 -10
- data/lib/paper_trail_diff/activity_grouping.rb +0 -38
- data/lib/paper_trail_diff/batch_safety.rb +0 -55
- data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
- data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
- data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
- data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
|
@@ -43,12 +43,20 @@ module PaperTrailDiff
|
|
|
43
43
|
end
|
|
44
44
|
end
|
|
45
45
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
46
|
+
# `activity_tree` names the association paths whose changes also select a
|
|
47
|
+
# root, as an activity analysis reports them. Without one, only a root's
|
|
48
|
+
# own versions select it.
|
|
49
|
+
#: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
|
|
50
|
+
def initialize(scope, time_range:, limit:, historical_filter: nil, # rubocop:disable Metrics/ParameterLists
|
|
51
|
+
max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil)
|
|
49
52
|
@scope = normalize_scope(scope)
|
|
53
|
+
reject_unversioned!
|
|
50
54
|
@time_range = time_range
|
|
51
55
|
@limit = validate_limit(limit)
|
|
56
|
+
@related = if activity_tree
|
|
57
|
+
AssociationActivitySelection.new(model, tree: activity_tree,
|
|
58
|
+
time_range: time_range)
|
|
59
|
+
end
|
|
52
60
|
@historical_filter = unless historical_filter.nil?
|
|
53
61
|
HistoricalFilter.new(base_class, predicate: historical_filter,
|
|
54
62
|
time_range: time_range, limit: @limit,
|
|
@@ -58,17 +66,11 @@ module PaperTrailDiff
|
|
|
58
66
|
|
|
59
67
|
#: () -> Result
|
|
60
68
|
def call
|
|
61
|
-
|
|
69
|
+
related = @related&.call || []
|
|
70
|
+
queries = subqueries(related)
|
|
71
|
+
return database_selection(queries) if queries
|
|
62
72
|
|
|
63
|
-
|
|
64
|
-
candidates = @historical_filter.call(candidates) if @historical_filter && candidates.any?
|
|
65
|
-
return Result.new(records: [], unreachable: []) if candidates.empty?
|
|
66
|
-
|
|
67
|
-
live = live_ids(candidates)
|
|
68
|
-
Result.new(
|
|
69
|
-
records: selected_records(live),
|
|
70
|
-
unreachable: (candidates - live).map { |id| identity(id) }.freeze
|
|
71
|
-
)
|
|
73
|
+
plucked_selection(versioned_ids | AssociationActivitySelection.values(related).map(&:to_s))
|
|
72
74
|
end
|
|
73
75
|
|
|
74
76
|
private
|
|
@@ -77,43 +79,80 @@ module PaperTrailDiff
|
|
|
77
79
|
# @rbs @time_range: TimeRange?
|
|
78
80
|
# @rbs @limit: Integer
|
|
79
81
|
# @rbs @historical_filter: untyped
|
|
82
|
+
# @rbs @related: AssociationActivitySelection?
|
|
80
83
|
|
|
81
84
|
# Leaves the candidate set in the database. Plucking every root changed in
|
|
82
85
|
# the window would cost memory and a statement proportional to all activity
|
|
83
86
|
# in the window -- not to the relation or `limit:` -- so a report on one
|
|
84
87
|
# record could read every id in a busy table. A subquery keeps the work
|
|
85
88
|
# bounded by what the relation and the deletions actually contain.
|
|
86
|
-
#: () -> Result
|
|
87
|
-
def database_selection
|
|
88
|
-
candidates = window_versions.select(:item_id)
|
|
89
|
+
#: (Array[AssociationActivitySelection::Query]) -> Result
|
|
90
|
+
def database_selection(related)
|
|
91
|
+
candidates = [window_versions.select(:item_id)] + related.map(&:relation)
|
|
92
|
+
missing = (missing_ids + related_missing_ids(related)).uniq.sort
|
|
89
93
|
Result.new(
|
|
90
94
|
records: selected_records(candidates),
|
|
91
|
-
unreachable:
|
|
95
|
+
unreachable: missing.map { |id| identity(id) }.freeze
|
|
92
96
|
)
|
|
93
97
|
end
|
|
94
98
|
|
|
99
|
+
# Comparing in SQL needs every subquery's column to share the key's type.
|
|
100
|
+
#: (Array[AssociationActivitySelection::source]) -> Array[AssociationActivitySelection::Query]?
|
|
101
|
+
def subqueries(related)
|
|
102
|
+
return unless @historical_filter.nil? && comparable_keys?
|
|
103
|
+
|
|
104
|
+
queries = related.grep(AssociationActivitySelection::Query) #: Array[AssociationActivitySelection::Query]
|
|
105
|
+
matching = queries.select { |ids| ids.type == key_type }
|
|
106
|
+
matching if matching.length == related.length
|
|
107
|
+
end
|
|
108
|
+
|
|
109
|
+
# Which candidates still have a row is asked without the relation's
|
|
110
|
+
# conditions, so that "filtered out" and "no longer exists" stay
|
|
111
|
+
# separable. A filter then reads the history of the relation's records
|
|
112
|
+
# only, whose order and page choose among those that match, and of the
|
|
113
|
+
# deleted ones, which no relation can test. Those it lists, as without a
|
|
114
|
+
# filter, but does not count toward `limit:`.
|
|
115
|
+
#: (Array[String]) -> Result
|
|
116
|
+
def plucked_selection(candidates)
|
|
117
|
+
live = ids_in(base_class.unscoped, candidates)
|
|
118
|
+
missing = candidates - live
|
|
119
|
+
if (filter = @historical_filter)
|
|
120
|
+
live = filter.call(ids_in(@scope.except(:order, :limit, :offset), live).uniq)
|
|
121
|
+
missing = filter.call(missing, counted: false)
|
|
122
|
+
end
|
|
123
|
+
Result.new(records: selected_records([live]),
|
|
124
|
+
unreachable: missing.sort.map { |id| identity(id) }.freeze)
|
|
125
|
+
end
|
|
126
|
+
|
|
95
127
|
# Comparing the two columns in SQL needs them to share a type: PostgreSQL
|
|
96
|
-
# rejects an integer key against a string item_id outright.
|
|
128
|
+
# rejects an integer key against a string item_id outright. A composite
|
|
129
|
+
# key names no single attribute, so it has no type and never matches.
|
|
97
130
|
#: () -> bool
|
|
98
131
|
def comparable_keys?
|
|
99
|
-
|
|
132
|
+
version_class.type_for_attribute('item_id').type == key_type
|
|
133
|
+
end
|
|
100
134
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
135
|
+
#: () -> Symbol?
|
|
136
|
+
def key_type
|
|
137
|
+
base_class.type_for_attribute(primary_key).type
|
|
138
|
+
end
|
|
139
|
+
|
|
140
|
+
#: (Array[AssociationActivitySelection::Query]) -> Array[String]
|
|
141
|
+
def related_missing_ids(related)
|
|
142
|
+
live = base_class.unscoped.select(primary_key).arel
|
|
143
|
+
related.flat_map { |ids| ids.missing(live) }.map(&:to_s)
|
|
104
144
|
end
|
|
105
145
|
|
|
106
146
|
# Changed in the window but without a row, found with an anti-join instead
|
|
107
147
|
# of comparing two plucked lists.
|
|
108
148
|
#: () -> Array[String]
|
|
109
149
|
def missing_ids
|
|
110
|
-
|
|
111
|
-
window_versions.where.not(item_id: live).distinct.pluck(:item_id).map(&:to_s).uniq.sort
|
|
150
|
+
window_versions.where.not(item_id: base_class.unscoped).distinct.pluck(:item_id).map(&:to_s)
|
|
112
151
|
end
|
|
113
152
|
|
|
114
153
|
#: () -> untyped
|
|
115
154
|
def window_versions
|
|
116
|
-
relation =
|
|
155
|
+
relation = VersionQuery.for_model(model)
|
|
117
156
|
range = @time_range
|
|
118
157
|
range ? range.scope(relation) : relation
|
|
119
158
|
end
|
|
@@ -127,16 +166,21 @@ module PaperTrailDiff
|
|
|
127
166
|
raise ConfigurationError, 'scope: must be an ActiveRecord relation or model class'
|
|
128
167
|
end
|
|
129
168
|
|
|
130
|
-
|
|
131
|
-
|
|
169
|
+
scope.all
|
|
170
|
+
end
|
|
171
|
+
|
|
172
|
+
#: () -> void
|
|
173
|
+
def reject_unversioned!
|
|
174
|
+
return if Support.versioned?(model)
|
|
132
175
|
|
|
133
176
|
raise UnversionedAssociationError,
|
|
134
|
-
"scope: #{
|
|
177
|
+
"scope: #{model} is not versioned, so it has no history to select from"
|
|
135
178
|
end
|
|
136
179
|
|
|
180
|
+
# No Integer subclass has instances, so this is `is_a?` by another name.
|
|
137
181
|
#: (Integer) -> Integer
|
|
138
182
|
def validate_limit(limit)
|
|
139
|
-
return limit if limit.
|
|
183
|
+
return limit if limit.instance_of?(Integer) && limit.positive?
|
|
140
184
|
|
|
141
185
|
raise ConfigurationError, 'limit: must be a positive Integer'
|
|
142
186
|
end
|
|
@@ -146,29 +190,28 @@ module PaperTrailDiff
|
|
|
146
190
|
# version table alone so that it does not depend on rows still existing.
|
|
147
191
|
#: () -> Array[String]
|
|
148
192
|
def versioned_ids
|
|
149
|
-
window_versions.distinct.pluck(:item_id).map(&:to_s)
|
|
193
|
+
window_versions.distinct.pluck(:item_id).map(&:to_s)
|
|
150
194
|
end
|
|
151
195
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
#: (Array[String]) -> Array[String]
|
|
155
|
-
def live_ids(candidates)
|
|
196
|
+
#: (untyped, Array[String]) -> Array[String]
|
|
197
|
+
def ids_in(relation, candidates)
|
|
156
198
|
candidates.each_slice(PAGE_SIZE).flat_map do |slice|
|
|
157
|
-
|
|
199
|
+
relation.where(primary_key => slice).pluck(primary_key).map(&:to_s)
|
|
158
200
|
end
|
|
159
201
|
end
|
|
160
202
|
|
|
161
203
|
# Deduplicate records rather than adding SQL DISTINCT: an otherwise valid
|
|
162
204
|
# relation may order by joined columns or select a PostgreSQL json column.
|
|
163
205
|
# Read bounded pages until the relation ends or too many unique roots appear.
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
206
|
+
# Each candidate source is an id list or a subquery; a record matching any
|
|
207
|
+
# of them is selected.
|
|
208
|
+
#: (Array[untyped]) -> Array[untyped]
|
|
209
|
+
def selected_records(candidates)
|
|
210
|
+
relation = candidate_relation(candidates)
|
|
168
211
|
records = {} #: Hash[untyped, untyped]
|
|
169
212
|
consumed = 0
|
|
170
213
|
loop do
|
|
171
|
-
page = record_page(
|
|
214
|
+
page = record_page(relation, consumed)
|
|
172
215
|
page.each { |record| records[record.id] ||= record }
|
|
173
216
|
reject_oversized!(records.length)
|
|
174
217
|
break if page.length < PAGE_SIZE
|
|
@@ -178,15 +221,20 @@ module PaperTrailDiff
|
|
|
178
221
|
records.values.freeze
|
|
179
222
|
end
|
|
180
223
|
|
|
224
|
+
#: (Array[untyped]) -> untyped
|
|
225
|
+
def candidate_relation(candidates)
|
|
226
|
+
candidates.map do |ids|
|
|
227
|
+
conditions = { primary_key => ids } #: Hash[untyped, untyped]
|
|
228
|
+
ordered_scope.where(conditions)
|
|
229
|
+
end.reduce(:or)
|
|
230
|
+
end
|
|
231
|
+
|
|
181
232
|
#: (untyped, Integer) -> Array[untyped]
|
|
182
|
-
def record_page(
|
|
233
|
+
def record_page(relation, consumed)
|
|
183
234
|
count = page_limit(consumed)
|
|
184
235
|
return [] if count.zero?
|
|
185
236
|
|
|
186
|
-
|
|
187
|
-
conditions = { primary_key => live } #: Hash[untyped, untyped]
|
|
188
|
-
ordered_scope.where(conditions)
|
|
189
|
-
.offset((@scope.offset_value || 0) + consumed).limit(count).to_a
|
|
237
|
+
relation.offset((@scope.offset_value || 0) + consumed).limit(count)
|
|
190
238
|
end
|
|
191
239
|
|
|
192
240
|
# Preserve explicit ordering: SQL Server rejects duplicate ORDER BY columns,
|
|
@@ -220,22 +268,30 @@ module PaperTrailDiff
|
|
|
220
268
|
|
|
221
269
|
#: () -> String
|
|
222
270
|
def item_type
|
|
223
|
-
base_class.name
|
|
271
|
+
base_class.name
|
|
272
|
+
end
|
|
273
|
+
|
|
274
|
+
# A relation delegates class methods to its model, so every mutation here,
|
|
275
|
+
# which drops `.model`, answers the same.
|
|
276
|
+
# mutant:disable
|
|
277
|
+
#: () -> untyped
|
|
278
|
+
def model
|
|
279
|
+
@scope.model
|
|
224
280
|
end
|
|
225
281
|
|
|
226
282
|
#: () -> untyped
|
|
227
283
|
def base_class
|
|
228
|
-
|
|
284
|
+
model.base_class
|
|
229
285
|
end
|
|
230
286
|
|
|
231
287
|
#: () -> untyped
|
|
232
288
|
def primary_key
|
|
233
|
-
|
|
289
|
+
model.primary_key
|
|
234
290
|
end
|
|
235
291
|
|
|
236
292
|
#: () -> untyped
|
|
237
293
|
def version_class
|
|
238
|
-
|
|
294
|
+
model.paper_trail.version_class
|
|
239
295
|
end
|
|
240
296
|
end
|
|
241
297
|
end
|
|
@@ -102,7 +102,7 @@ module PaperTrailDiff
|
|
|
102
102
|
end
|
|
103
103
|
|
|
104
104
|
@kind = kind
|
|
105
|
-
@records = records
|
|
105
|
+
@records = ordered(records)
|
|
106
106
|
@identity_index_cache = identity_index_cache || IdentityIndexCache.new
|
|
107
107
|
@transition = transition
|
|
108
108
|
@serial = SERIALS.next_serial
|
|
@@ -124,6 +124,21 @@ module PaperTrailDiff
|
|
|
124
124
|
)
|
|
125
125
|
end
|
|
126
126
|
|
|
127
|
+
# Collections are documented in record type, then ID, order wherever they
|
|
128
|
+
# were read from. Most arrive sorted, so they are checked before sorting.
|
|
129
|
+
#: (Array[RecordSnapshot]) -> Array[RecordSnapshot]
|
|
130
|
+
def ordered(records)
|
|
131
|
+
keys = records.map { |record| Support.sortable_identity(record.type, record.id) }
|
|
132
|
+
return records.sort_by.with_index { |_, index| keys.fetch(index) }.freeze unless sorted?(keys)
|
|
133
|
+
|
|
134
|
+
records.frozen? ? records : records.dup.freeze
|
|
135
|
+
end
|
|
136
|
+
|
|
137
|
+
#: (Array[Array[untyped]]) -> bool
|
|
138
|
+
def sorted?(keys)
|
|
139
|
+
keys.each_cons(2).all? { |left, right| (left <=> right).to_i <= 0 }
|
|
140
|
+
end
|
|
141
|
+
|
|
127
142
|
#: (AssociationSnapshot) -> CollectionTransition?
|
|
128
143
|
def transition_from(association)
|
|
129
144
|
@transition if @transition&.from?(association)
|
|
@@ -200,9 +200,8 @@ module PaperTrailDiff
|
|
|
200
200
|
path,
|
|
201
201
|
reifier
|
|
202
202
|
)
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
child_path = Support.association_path(path, reflection.name.to_s)
|
|
203
|
+
records = members(record, reflection)
|
|
204
|
+
child_path = Support.association_path(path, reflection.name)
|
|
206
205
|
@structural_columns[child_path] ||= @traversal.incoming_relationship_columns(reflection)
|
|
207
206
|
snapshot = AssociationSnapshot.new(
|
|
208
207
|
kind: reflection.macro,
|
|
@@ -211,6 +210,14 @@ module PaperTrailDiff
|
|
|
211
210
|
@pool.association(child_path, snapshot)
|
|
212
211
|
end
|
|
213
212
|
|
|
213
|
+
# A reified history can hold a member PaperTrail could not rebuild. A
|
|
214
|
+
# through loads a record once per join that reaches it; it is one member,
|
|
215
|
+
# as Active Record compares records by class and id.
|
|
216
|
+
#: (untyped, untyped) -> Array[untyped]
|
|
217
|
+
def members(record, reflection)
|
|
218
|
+
Array(record.public_send(reflection.name)).compact.uniq
|
|
219
|
+
end
|
|
220
|
+
|
|
214
221
|
#: (Array[untyped], AssociationTree, String, untyped) -> Array[RecordSnapshot]
|
|
215
222
|
def normalize_children(records, tree, path, reifier)
|
|
216
223
|
reflections_by_class = {} #: Hash[untyped, Array[untyped]]
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
module PaperTrailDiff
|
|
5
5
|
# Internal helpers for isolating and serializing values held by result objects.
|
|
6
|
-
module Support
|
|
6
|
+
module Support # rubocop:disable Metrics/ModuleLength
|
|
7
7
|
module_function
|
|
8
8
|
|
|
9
9
|
#: (untyped) -> untyped
|
|
@@ -44,9 +44,28 @@ module PaperTrailDiff
|
|
|
44
44
|
end
|
|
45
45
|
end
|
|
46
46
|
|
|
47
|
+
# Records sort by type first so that mixed id types stay comparable, then
|
|
48
|
+
# naturally within one type. Ordering by the printed form instead would put
|
|
49
|
+
# id 10 before id 2, which is deterministic but reads as unsorted wherever a
|
|
50
|
+
# result is rendered.
|
|
51
|
+
#: (untyped, untyped) -> Array[untyped]
|
|
52
|
+
def sortable_identity(type, id)
|
|
53
|
+
key = case id
|
|
54
|
+
when Numeric then [0, id]
|
|
55
|
+
when String, Symbol then [1, id.to_s]
|
|
56
|
+
else [2, id.inspect]
|
|
57
|
+
end
|
|
58
|
+
[type.to_s, key]
|
|
59
|
+
end
|
|
60
|
+
|
|
47
61
|
#: (untyped) -> Array[untyped]
|
|
48
62
|
def chronological_version_key(version)
|
|
49
|
-
|
|
63
|
+
version_key(version.created_at, version.id)
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
#: (untyped, untyped) -> Array[untyped]
|
|
67
|
+
def version_key(created_at, id)
|
|
68
|
+
[created_at, id.to_s.rjust(32, '0')]
|
|
50
69
|
end
|
|
51
70
|
|
|
52
71
|
# Ordering falls back to the id whenever timestamps tie, which recovers the
|
|
@@ -65,11 +84,24 @@ module PaperTrailDiff
|
|
|
65
84
|
#: (Array[untyped]) -> Array[untyped]?
|
|
66
85
|
def ambiguous_pair(sorted)
|
|
67
86
|
sorted.each_cons(2).find do |left, right|
|
|
68
|
-
left.created_at == right.created_at &&
|
|
69
|
-
!(sequential_id?(left.id) && sequential_id?(right.id))
|
|
87
|
+
left.created_at == right.created_at && !orderable_tie?(left, right)
|
|
70
88
|
end
|
|
71
89
|
end
|
|
72
90
|
|
|
91
|
+
# Ids order versions saved in one instant only when they count up in one
|
|
92
|
+
# table. Two version tables count separately, so ids there say nothing.
|
|
93
|
+
#: (untyped, untyped) -> bool
|
|
94
|
+
def orderable_tie?(left, right)
|
|
95
|
+
version_table(left) == version_table(right) &&
|
|
96
|
+
sequential_id?(left.id) && sequential_id?(right.id)
|
|
97
|
+
end
|
|
98
|
+
|
|
99
|
+
#: (untyped) -> untyped
|
|
100
|
+
def version_table(version)
|
|
101
|
+
version.class.respond_to?(:table_name) ? version.class.table_name : version.class.name
|
|
102
|
+
end
|
|
103
|
+
private_class_method :version_table
|
|
104
|
+
|
|
73
105
|
# Versions sharing a timestamp, whether or not their ids order them. PT-AT
|
|
74
106
|
# indexes association membership per version but resolves it by timestamp,
|
|
75
107
|
# so association state cannot be told apart across such a pair even when the
|
|
@@ -124,9 +156,9 @@ module PaperTrailDiff
|
|
|
124
156
|
raise(ConfigurationError, 'versions have incomparable timestamps')
|
|
125
157
|
end
|
|
126
158
|
|
|
127
|
-
#: (String, String) -> String
|
|
159
|
+
#: (String, String | Symbol) -> String
|
|
128
160
|
def association_path(parent, name)
|
|
129
|
-
parent.empty? ? name : "#{parent}.#{name}"
|
|
161
|
+
parent.empty? ? name.to_s : "#{parent}.#{name}"
|
|
130
162
|
end
|
|
131
163
|
|
|
132
164
|
#: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
|
|
@@ -3,6 +3,10 @@
|
|
|
3
3
|
|
|
4
4
|
module PaperTrailDiff
|
|
5
5
|
# Validates and applies a finite wall-clock range without loading model state.
|
|
6
|
+
#
|
|
7
|
+
# A Date is a whole day and a String a local time, both in Time.zone, as
|
|
8
|
+
# Rails reads them, or in UTC without one: never the server's own zone. An
|
|
9
|
+
# inclusive Date end runs through that day.
|
|
6
10
|
class TimeRange
|
|
7
11
|
attr_reader :begin_time #: Time
|
|
8
12
|
attr_reader :end_time #: Time
|
|
@@ -14,8 +18,8 @@ module PaperTrailDiff
|
|
|
14
18
|
end
|
|
15
19
|
|
|
16
20
|
@begin_time = coerce_time(value.begin, boundary: :begin)
|
|
17
|
-
@
|
|
18
|
-
@
|
|
21
|
+
@exclude_end = value.exclude_end? || calendar_date?(value.end)
|
|
22
|
+
@end_time = coerce_time(end_value(value), boundary: :end)
|
|
19
23
|
validate_order!
|
|
20
24
|
freeze
|
|
21
25
|
end
|
|
@@ -40,8 +44,7 @@ module PaperTrailDiff
|
|
|
40
44
|
|
|
41
45
|
#: (untyped) -> untyped
|
|
42
46
|
def trailing_scope(relation)
|
|
43
|
-
|
|
44
|
-
relation.where(after_end(column))
|
|
47
|
+
relation.where(after_end(relation.arel_table[:created_at]))
|
|
45
48
|
end
|
|
46
49
|
|
|
47
50
|
# Each item's earliest version after the range, keyed by item id. One row
|
|
@@ -49,11 +52,11 @@ module PaperTrailDiff
|
|
|
49
52
|
# the query stays portable; a timestamp tie keeps the lower id.
|
|
50
53
|
#: (untyped) -> Hash[String, untyped]
|
|
51
54
|
def first_trailing_versions(relation)
|
|
52
|
-
table = relation.
|
|
55
|
+
table = relation.arel_table
|
|
53
56
|
first_after = VersionQuery.no_earlier_version(table) do |earlier|
|
|
54
57
|
after_end(earlier[:created_at])
|
|
55
58
|
end
|
|
56
|
-
versions = VersionQuery.chronological(trailing_scope(relation).where(first_after))
|
|
59
|
+
versions = VersionQuery.chronological(trailing_scope(relation).where(first_after))
|
|
57
60
|
first = {} #: Hash[String, untyped]
|
|
58
61
|
versions.each { |version| first[version.item_id.to_s] ||= version }
|
|
59
62
|
first
|
|
@@ -75,23 +78,39 @@ module PaperTrailDiff
|
|
|
75
78
|
|
|
76
79
|
#: (untyped, boundary: Symbol) -> Time
|
|
77
80
|
def coerce_time(value, boundary:)
|
|
78
|
-
unless value.respond_to?(:to_time)
|
|
79
|
-
raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
|
|
80
|
-
end
|
|
81
|
-
|
|
82
81
|
time_value(value).getutc.freeze
|
|
83
|
-
rescue ArgumentError, NoMethodError, TypeError
|
|
84
|
-
raise InvalidTimeRangeError,
|
|
85
|
-
"`within` #{boundary} must be time-like",
|
|
86
|
-
cause: e
|
|
82
|
+
rescue ArgumentError, NoMethodError, TypeError
|
|
83
|
+
raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
|
|
87
84
|
end
|
|
88
85
|
|
|
89
|
-
|
|
86
|
+
# Anything else names its instant, and `getutc` reads it without
|
|
87
|
+
# `to_time`, which Active Support 8.0 and older warn will change on a
|
|
88
|
+
# zoned time, and without changing the caller's own value as `utc` does.
|
|
89
|
+
#: (untyped) -> untyped
|
|
90
90
|
def time_value(value)
|
|
91
|
-
return value if value.is_a?(
|
|
91
|
+
return zone.parse(value) || raise(ArgumentError) if value.is_a?(String)
|
|
92
|
+
return zone.local(value.year, value.month, value.day) if calendar_date?(value)
|
|
93
|
+
|
|
94
|
+
value
|
|
95
|
+
end
|
|
96
|
+
|
|
97
|
+
# An inclusive date end runs through the day: to the next one's start.
|
|
98
|
+
#: (Range[untyped]) -> untyped
|
|
99
|
+
def end_value(range)
|
|
100
|
+
last = range.end
|
|
101
|
+
calendar_date?(last) && !range.exclude_end? ? last.next_day : last
|
|
102
|
+
end
|
|
103
|
+
|
|
104
|
+
# A DateTime is a Date too, but names its instant.
|
|
105
|
+
#: (untyped) -> bool
|
|
106
|
+
def calendar_date?(value)
|
|
107
|
+
value.instance_of?(Date)
|
|
108
|
+
end
|
|
92
109
|
|
|
93
|
-
|
|
94
|
-
|
|
110
|
+
#: () -> untyped
|
|
111
|
+
def zone
|
|
112
|
+
time = Time #: untyped
|
|
113
|
+
time.zone || time.find_zone!('UTC')
|
|
95
114
|
end
|
|
96
115
|
|
|
97
116
|
#: () -> void
|
|
@@ -4,18 +4,18 @@
|
|
|
4
4
|
module PaperTrailDiff
|
|
5
5
|
# Selects in-range root versions plus one later reconstruction boundary.
|
|
6
6
|
class TimeVersionRange
|
|
7
|
-
#: (untyped, time_range: TimeRange,
|
|
8
|
-
def initialize(record, time_range:, version_scope
|
|
7
|
+
#: (untyped, time_range: TimeRange, version_scope: untyped, live_endpoint: untyped) -> void
|
|
8
|
+
def initialize(record, time_range:, version_scope:, live_endpoint:)
|
|
9
9
|
@record = record
|
|
10
10
|
@time_range = time_range
|
|
11
11
|
@version_scope = version_scope
|
|
12
12
|
@live_endpoint = live_endpoint
|
|
13
13
|
end
|
|
14
14
|
|
|
15
|
-
#: (
|
|
16
|
-
def select_plan(context_required:
|
|
15
|
+
#: (context_required: bool) -> RootVersionPlan
|
|
16
|
+
def select_plan(context_required:)
|
|
17
17
|
relation = Endpoint.versions(@record)
|
|
18
|
-
in_range = ordered(@time_range.scope(relation)
|
|
18
|
+
in_range = ordered(@time_range.scope(relation))
|
|
19
19
|
RootVersionSelection.new(
|
|
20
20
|
in_range: in_range,
|
|
21
21
|
selected: VersionScopeFilter.new(@version_scope).call(@time_range.scope(relation),
|
|
@@ -46,21 +46,21 @@ module PaperTrailDiff
|
|
|
46
46
|
return empty_history if plan.empty?
|
|
47
47
|
|
|
48
48
|
versions = plan.versions
|
|
49
|
-
@snapshotter.prepare(@record, versions)
|
|
50
|
-
steps = build_steps(plan)
|
|
51
|
-
final = plan.closes_on_destroy ? nil :
|
|
52
|
-
[steps,
|
|
49
|
+
snapshots = @snapshotter.prepare(@record, versions)
|
|
50
|
+
steps = build_steps(plan, snapshots)
|
|
51
|
+
final = plan.closes_on_destroy ? nil : snapshots.call(plan.final_endpoint)
|
|
52
|
+
[steps, snapshots.call(versions.first), final]
|
|
53
53
|
end
|
|
54
54
|
|
|
55
|
-
#: (RootVersionPlan) -> Array[Step]
|
|
56
|
-
def build_steps(plan)
|
|
55
|
+
#: (RootVersionPlan, untyped) -> Array[Step]
|
|
56
|
+
def build_steps(plan, snapshots)
|
|
57
57
|
captured_at = Time.now.utc if plan.closing_record
|
|
58
58
|
plan.steps.map do |from_endpoint, to_endpoint|
|
|
59
59
|
Step.new(
|
|
60
60
|
from_version: from_endpoint,
|
|
61
61
|
to_version: to_endpoint,
|
|
62
62
|
captured_at: captured_at,
|
|
63
|
-
diff: Engine.compare(
|
|
63
|
+
diff: Engine.compare(snapshots.call(from_endpoint), snapshots.call(to_endpoint))
|
|
64
64
|
)
|
|
65
65
|
end.freeze
|
|
66
66
|
end
|
|
@@ -122,9 +122,17 @@ module PaperTrailDiff
|
|
|
122
122
|
VersionQuery.chronological(Endpoint.versions(@record))
|
|
123
123
|
end
|
|
124
124
|
|
|
125
|
+
# A batch passes each root the window it already moved to transaction
|
|
126
|
+
# edges; a single record's window is moved here.
|
|
125
127
|
#: (untyped) -> TimeRange?
|
|
126
128
|
def build_time_range(within)
|
|
127
|
-
|
|
129
|
+
return if within.nil?
|
|
130
|
+
return within if within.instance_of?(TimeRange)
|
|
131
|
+
|
|
132
|
+
range = TimeRange.new(within)
|
|
133
|
+
return range unless Support.versioned?(@record.class)
|
|
134
|
+
|
|
135
|
+
TransactionCut.windows(@record.class, [@record], range).fetch(@record.id.to_s, range)
|
|
128
136
|
end
|
|
129
137
|
|
|
130
138
|
#: () -> void
|
|
@@ -2,22 +2,35 @@
|
|
|
2
2
|
# rbs_inline: enabled
|
|
3
3
|
|
|
4
4
|
module PaperTrailDiff
|
|
5
|
-
#
|
|
5
|
+
# Prepares the snapshot store for TimelineBuilder, one root at a time.
|
|
6
6
|
class TimelineSnapshotProvider
|
|
7
7
|
#: (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
|
|
8
8
|
def initialize(store, live_snapshotter:)
|
|
9
9
|
@store = store
|
|
10
10
|
@live_snapshotter = live_snapshotter
|
|
11
|
-
@snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
|
|
12
11
|
end
|
|
13
12
|
|
|
14
|
-
#: (untyped, Array[untyped]) ->
|
|
13
|
+
#: (untyped, Array[untyped]) -> PreparedTimelineSnapshots
|
|
15
14
|
def prepare(record, versions)
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
15
|
+
history = @store.prepare(record, versions)
|
|
16
|
+
PreparedTimelineSnapshots.new(history, store: @store, live_snapshotter: @live_snapshotter)
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
# @rbs @store: HistoricalSnapshotStore
|
|
20
|
+
# @rbs @live_snapshotter: untyped
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
# One root's timeline snapshots, read with the history prepared for it.
|
|
24
|
+
# Adjacent steps share endpoints, so each immutable snapshot, including a
|
|
25
|
+
# nil create state, is kept for this root only and released with it, and
|
|
26
|
+
# batch memory does not retain every reconstructed graph.
|
|
27
|
+
class PreparedTimelineSnapshots
|
|
28
|
+
#: (PreparedHistory?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
|
|
29
|
+
def initialize(history, store:, live_snapshotter:)
|
|
30
|
+
@history = history
|
|
31
|
+
@store = store
|
|
32
|
+
@live_snapshotter = live_snapshotter
|
|
33
|
+
@snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
|
|
21
34
|
end
|
|
22
35
|
|
|
23
36
|
# A window closing on current state ends at the live record rather than at a
|
|
@@ -28,19 +41,13 @@ module PaperTrailDiff
|
|
|
28
41
|
return @snapshots[key] if @snapshots.key?(key)
|
|
29
42
|
|
|
30
43
|
@snapshots[key] = if Endpoint.record?(endpoint)
|
|
31
|
-
|
|
44
|
+
@live_snapshotter.call(endpoint)
|
|
32
45
|
else
|
|
33
|
-
@store.uncached(endpoint, endpoint)
|
|
46
|
+
@store.uncached(endpoint, endpoint, history: @history)
|
|
34
47
|
end
|
|
35
48
|
end
|
|
36
49
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
#: (untyped) -> RecordSnapshot?
|
|
40
|
-
def live_snapshot(record)
|
|
41
|
-
@live_snapshotter.call(record)
|
|
42
|
-
end
|
|
43
|
-
|
|
50
|
+
# @rbs @history: PreparedHistory?
|
|
44
51
|
# @rbs @store: HistoricalSnapshotStore
|
|
45
52
|
# @rbs @live_snapshotter: untyped
|
|
46
53
|
# @rbs @snapshots: Hash[Array[untyped], RecordSnapshot?]
|