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
|
@@ -146,6 +146,13 @@ module PaperTrailDiff
|
|
|
146
146
|
owners ? owners.fetch(owner.id.to_s, empty) : group.fetch(:ids)
|
|
147
147
|
end
|
|
148
148
|
|
|
149
|
+
# PT-AT records a checkpoint's membership as it is when the checkpoint is
|
|
150
|
+
# saved, so a tag attached earlier in the checkpoint's own transaction is a
|
|
151
|
+
# member there, unlike other associations, which a version reads as they
|
|
152
|
+
# were before its transaction. A member created in that transaction has no
|
|
153
|
+
# earlier state, so it is read as it was created, from its creation on.
|
|
154
|
+
# The checkpoint's membership also stands for earlier points, since the
|
|
155
|
+
# previous root version; the member did not exist at those yet.
|
|
149
156
|
#: (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
|
|
150
157
|
def habtm_records(record, reflection, boundary, habtm_boundary, ranked)
|
|
151
158
|
transaction_id = transaction_id_for(habtm_boundary)
|
|
@@ -155,10 +162,17 @@ module PaperTrailDiff
|
|
|
155
162
|
ids = @habtm.fetch(edge_key(record.class, reflection), empty)[transaction_id.to_s]
|
|
156
163
|
return unless ids
|
|
157
164
|
|
|
158
|
-
|
|
165
|
+
created = VersionBoundary.transaction_id(boundary).to_s == transaction_id.to_s
|
|
166
|
+
members = ids.filter_map { |id| habtm_member(reflection.klass, id, boundary, created) }
|
|
159
167
|
@conditions.select(reflection, members, ranked: ranked)
|
|
160
168
|
end
|
|
161
169
|
|
|
170
|
+
#: (untyped, untyped, untyped, bool) -> untyped
|
|
171
|
+
def habtm_member(model_class, id, boundary, created)
|
|
172
|
+
@records.record_before(model_class, id, boundary) ||
|
|
173
|
+
(@records.record_created_in(model_class, id, boundary) if created)
|
|
174
|
+
end
|
|
175
|
+
|
|
162
176
|
# A has_many through reads its parts unranked, as its query does. Its own
|
|
163
177
|
# scope applies to each row, and a ranked read then keeps a record reached
|
|
164
178
|
# twice as one member.
|
|
@@ -21,10 +21,9 @@ module PaperTrailDiff
|
|
|
21
21
|
@root_versions = root_versions
|
|
22
22
|
@tree = tree
|
|
23
23
|
@traversal = traversal
|
|
24
|
+
start_at = VersionBoundary.transaction_start(root_versions, start_at)
|
|
24
25
|
@records = PreparedRecordIndex.new(start_at, end_at: end_at, live_records: live_records)
|
|
25
|
-
@activity = PreparedActivityIndex.new(
|
|
26
|
-
@records, root_versions, start_at: start_at, end_at: end_at || root_versions.last.created_at
|
|
27
|
-
)
|
|
26
|
+
@activity = PreparedActivityIndex.new(@records, root_versions, start_at: start_at)
|
|
28
27
|
@history = PreparedHistory.new(@records, activity_index: @activity)
|
|
29
28
|
@edges = PreparedEdgeLoader.new(@records, root_versions, start_at: start_at)
|
|
30
29
|
@prepared = {} #: Hash[untyped, Array[String]]
|
|
@@ -133,6 +133,21 @@ module PaperTrailDiff
|
|
|
133
133
|
state_before(boundary)&.instantiate
|
|
134
134
|
end
|
|
135
135
|
|
|
136
|
+
# A record created in the boundary's own transaction has no state before
|
|
137
|
+
# it, yet a HABTM checkpoint saved later in that transaction records it as
|
|
138
|
+
# a member. Such a member is read as it was created, at a boundary after
|
|
139
|
+
# its creation; before it, the record did not exist yet.
|
|
140
|
+
#: (untyped) -> untyped
|
|
141
|
+
def record_created_in(boundary)
|
|
142
|
+
index = transaction_index(boundary)
|
|
143
|
+
return unless index
|
|
144
|
+
|
|
145
|
+
version = versions.fetch(index)
|
|
146
|
+
return unless version.event == 'create' && !VersionBoundary.at_or_after?(version, boundary)
|
|
147
|
+
|
|
148
|
+
state_after(index)&.instantiate
|
|
149
|
+
end
|
|
150
|
+
|
|
136
151
|
#: (untyped) -> PreparedRecordState?
|
|
137
152
|
def state_before(boundary)
|
|
138
153
|
index = boundary_index(boundary)
|
|
@@ -179,7 +194,7 @@ module PaperTrailDiff
|
|
|
179
194
|
[state_for(version), state_after(index)].compact
|
|
180
195
|
end
|
|
181
196
|
|
|
182
|
-
#: (untyped) -> [
|
|
197
|
+
#: (untyped) -> [PreparedRecordState, PreparedRecordState]?
|
|
183
198
|
def transition(version)
|
|
184
199
|
index = @version_positions[version.id.to_s]
|
|
185
200
|
return unless index
|
|
@@ -188,7 +203,7 @@ module PaperTrailDiff
|
|
|
188
203
|
after = state_after(index)
|
|
189
204
|
return unless before && after && before.model_class == after.model_class
|
|
190
205
|
|
|
191
|
-
[before
|
|
206
|
+
[before, after]
|
|
192
207
|
end
|
|
193
208
|
|
|
194
209
|
private
|
|
@@ -228,7 +243,7 @@ module PaperTrailDiff
|
|
|
228
243
|
|
|
229
244
|
#: (untyped) -> Integer?
|
|
230
245
|
def transaction_index(boundary)
|
|
231
|
-
transaction_id =
|
|
246
|
+
transaction_id = VersionBoundary.transaction_id(boundary)
|
|
232
247
|
return unless transaction_id
|
|
233
248
|
|
|
234
249
|
@transaction_positions[transaction_id]
|
|
@@ -238,9 +253,7 @@ module PaperTrailDiff
|
|
|
238
253
|
def build_transaction_positions
|
|
239
254
|
positions = {} #: Hash[untyped, Integer]
|
|
240
255
|
@versions.each_with_index do |version, index|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
transaction_id = version.transaction_id
|
|
256
|
+
transaction_id = VersionBoundary.transaction_id(version)
|
|
244
257
|
positions[transaction_id] ||= index if transaction_id
|
|
245
258
|
end
|
|
246
259
|
positions.freeze
|
|
@@ -304,6 +317,11 @@ module PaperTrailDiff
|
|
|
304
317
|
@series.fetch(identity(model_class, id)).record_before(boundary)
|
|
305
318
|
end
|
|
306
319
|
|
|
320
|
+
#: (untyped, untyped, untyped) -> untyped
|
|
321
|
+
def record_created_in(model_class, id, boundary)
|
|
322
|
+
@series.fetch(identity(model_class, id)).record_created_in(boundary)
|
|
323
|
+
end
|
|
324
|
+
|
|
307
325
|
#: (untyped, untyped, untyped) -> [bool, PreparedRecordState?]
|
|
308
326
|
def snapshot_state_before(model_class, id, boundary)
|
|
309
327
|
series = @series[identity(model_class, id)]
|
|
@@ -317,9 +335,15 @@ module PaperTrailDiff
|
|
|
317
335
|
[!prepared.nil?, prepared]
|
|
318
336
|
end
|
|
319
337
|
|
|
338
|
+
# Typed as a reified record's attributes are. A JSON or JSONB `object`
|
|
339
|
+
# column stores times and dates as strings, which PaperTrail does not cast
|
|
340
|
+
# back, and the transition is carried into snapshots built from records.
|
|
320
341
|
#: (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
|
|
321
342
|
def transition(model_class, id, version)
|
|
322
|
-
@series[identity(model_class, id)]&.transition(version)
|
|
343
|
+
states = @series[identity(model_class, id)]&.transition(version)
|
|
344
|
+
return unless states
|
|
345
|
+
|
|
346
|
+
[typed_attributes(states.fetch(0)), typed_attributes(states.fetch(1))]
|
|
323
347
|
end
|
|
324
348
|
|
|
325
349
|
#: (untyped, untyped, untyped, ?direct: bool) -> [bool, untyped]
|
|
@@ -370,6 +394,17 @@ module PaperTrailDiff
|
|
|
370
394
|
|
|
371
395
|
private
|
|
372
396
|
|
|
397
|
+
# A model whose records need their own initialization is cast by
|
|
398
|
+
# instantiating it, as reify does.
|
|
399
|
+
#: (PreparedRecordState) -> Hash[untyped, untyped]
|
|
400
|
+
def typed_attributes(state)
|
|
401
|
+
@direct_states[state] = @direct_loader.complete(state) unless @direct_states.key?(state)
|
|
402
|
+
typed = @direct_states[state]
|
|
403
|
+
return typed.attributes if typed
|
|
404
|
+
|
|
405
|
+
PreparedRecordState.new(state.instantiate).attributes
|
|
406
|
+
end
|
|
407
|
+
|
|
373
408
|
#: (untyped, String) -> bool
|
|
374
409
|
def generated_reader?(model, name)
|
|
375
410
|
model.define_attribute_methods
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
# rbs_inline: enabled
|
|
3
|
+
|
|
4
|
+
module PaperTrailDiff
|
|
5
|
+
# Runs one read's statements inside one database snapshot. Without one, a row
|
|
6
|
+
# that commits between two statements of the read can be seen by one of them
|
|
7
|
+
# and missed by another: an activity read then found a comment whose versions
|
|
8
|
+
# it had not read yet, and raised `KeyError`.
|
|
9
|
+
#
|
|
10
|
+
# PostgreSQL and MySQL (through mysql2 or trilogy), and adapters built on
|
|
11
|
+
# them such as PostGIS, run the read at REPEATABLE READ, which gives every
|
|
12
|
+
# statement of the transaction the same view. Other adapters get no snapshot;
|
|
13
|
+
# docs/reference.md lists them under limitations.
|
|
14
|
+
module ReadSnapshot
|
|
15
|
+
# The adapters whose subclasses take a snapshot, by name, since an
|
|
16
|
+
# application loads only the adapters it uses.
|
|
17
|
+
SNAPSHOT_ADAPTERS = %w[
|
|
18
|
+
ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
|
|
19
|
+
ActiveRecord::ConnectionAdapters::AbstractMysqlAdapter
|
|
20
|
+
].freeze
|
|
21
|
+
|
|
22
|
+
module_function
|
|
23
|
+
|
|
24
|
+
# Yields once. Each connection the values read through gets a snapshot
|
|
25
|
+
# transaction first, unless that connection already has a transaction open:
|
|
26
|
+
# its isolation level belongs to the caller, and this gem cannot change it.
|
|
27
|
+
# A value may be a model class, a relation, a record, or a version. Any
|
|
28
|
+
# other value reads no table and is ignored.
|
|
29
|
+
#: (Array[untyped]) { () -> untyped } -> untyped
|
|
30
|
+
def call(values, &block)
|
|
31
|
+
classes = connection_classes(values)
|
|
32
|
+
classes.reverse_each.reduce(block) do |inner, klass|
|
|
33
|
+
connection = klass.connection
|
|
34
|
+
next inner if !snapshot?(connection) || connection.transaction_open?
|
|
35
|
+
|
|
36
|
+
-> { klass.transaction(isolation: :repeatable_read) { inner.call } }
|
|
37
|
+
end.call
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
#: (untyped) -> bool
|
|
41
|
+
def snapshot?(connection)
|
|
42
|
+
connection.class.ancestors.any? { |ancestor| SNAPSHOT_ADAPTERS.include?(ancestor.name) }
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
# One class per connection: each read model and its version class, with the
|
|
46
|
+
# repeats through a shared connection dropped. An associated model on
|
|
47
|
+
# another database is not among them, so it is read outside the snapshot.
|
|
48
|
+
#: (Array[untyped]) -> Array[untyped]
|
|
49
|
+
def connection_classes(values)
|
|
50
|
+
values.filter_map { |value| model_for(value) }
|
|
51
|
+
.flat_map { |model| [model, model.paper_trail.version_class] }
|
|
52
|
+
.uniq(&:connection)
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
# The versioned model a value reads from, or nil.
|
|
56
|
+
#: (untyped) -> untyped
|
|
57
|
+
def model_for(value)
|
|
58
|
+
active_record = Object.const_get(:ActiveRecord) #: untyped
|
|
59
|
+
model = case value
|
|
60
|
+
when active_record.const_get(:Relation) then value.klass
|
|
61
|
+
when Class then value
|
|
62
|
+
else endpoint_model(value)
|
|
63
|
+
end
|
|
64
|
+
model if model.is_a?(Class) && Support.versioned?(model)
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
# A version reads the model of its item; a record reads its own class.
|
|
68
|
+
#: (untyped) -> untyped
|
|
69
|
+
def endpoint_model(value)
|
|
70
|
+
return Endpoint.model_class(value) if Endpoint.version?(value)
|
|
71
|
+
|
|
72
|
+
value.class if Endpoint.record?(value)
|
|
73
|
+
end
|
|
74
|
+
|
|
75
|
+
private_class_method :snapshot?, :model_for, :endpoint_model
|
|
76
|
+
end
|
|
77
|
+
end
|
|
@@ -14,9 +14,11 @@ module PaperTrailDiff
|
|
|
14
14
|
# An error is a specification, so it names the way out as well as the wall.
|
|
15
15
|
# A window ending at the present can never gain a later version, which makes
|
|
16
16
|
# "write a checkpoint afterwards" impossible advice on its own.
|
|
17
|
+
# A window closes on the current record when it reaches the present, so
|
|
18
|
+
# this is raised only when there is none to read.
|
|
17
19
|
INCOMPLETE = 'time range requires a later root version to reconstruct its ' \
|
|
18
|
-
'final change
|
|
19
|
-
'
|
|
20
|
+
'final change, and there is no current record to end at: narrow ' \
|
|
21
|
+
'the window to end before the last recorded version'
|
|
20
22
|
|
|
21
23
|
#: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
|
|
22
24
|
def initialize( # rubocop:disable Metrics/ParameterLists
|
|
@@ -14,6 +14,8 @@ module PaperTrailDiff
|
|
|
14
14
|
# ranking alone.
|
|
15
15
|
RELATION_VALUES = %i[where order reordering limit offset readonly strict_loading
|
|
16
16
|
extending].freeze
|
|
17
|
+
# Relation parts that load or shape rows without choosing them.
|
|
18
|
+
LOADING_VALUES = %i[includes preload select distinct].freeze
|
|
17
19
|
# Types whose stored values compare in Ruby as the database compares them,
|
|
18
20
|
# named rather than referenced so that loading needs no Active Model.
|
|
19
21
|
VALUE_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
|
|
@@ -54,7 +56,7 @@ module PaperTrailDiff
|
|
|
54
56
|
return if ranked && ranked_through?(reflection)
|
|
55
57
|
|
|
56
58
|
relation = scoped_relation(reflection, model_class)
|
|
57
|
-
return unless relation && plain_relation?(relation)
|
|
59
|
+
return unless relation && plain_relation?(relation, RELATION_VALUES)
|
|
58
60
|
|
|
59
61
|
clause = relation.where_clause - model_class.unscoped.where_clause
|
|
60
62
|
predicate = Reader.new(model_class).call(clause.ast)
|
|
@@ -63,6 +65,32 @@ module PaperTrailDiff
|
|
|
63
65
|
nil
|
|
64
66
|
end
|
|
65
67
|
|
|
68
|
+
# A relation's own where clause, default scope included, read as
|
|
69
|
+
# conditions on stored attributes; nil when it cannot be. Its order,
|
|
70
|
+
# limit, and offset choose a page of current rows rather than membership,
|
|
71
|
+
# and loading or selecting columns changes neither, so they are left out.
|
|
72
|
+
# A single-table subclass's type condition is left to the caller, as for
|
|
73
|
+
# an association. `none` selects nothing, whatever it is chained to.
|
|
74
|
+
#: (untyped, untyped) -> ScopeCondition?
|
|
75
|
+
def self.for_relation(relation, model_class)
|
|
76
|
+
return nothing if relation.null_relation?
|
|
77
|
+
|
|
78
|
+
return unless plain_relation?(relation, [*RELATION_VALUES, *LOADING_VALUES])
|
|
79
|
+
|
|
80
|
+
clause = relation.where_clause - model_class.unscoped.where_clause
|
|
81
|
+
new(model_class, Reader.new(model_class).call(clause.ast))
|
|
82
|
+
rescue Unreadable
|
|
83
|
+
nil
|
|
84
|
+
end
|
|
85
|
+
|
|
86
|
+
# A relation `none` built, whose where clause is SQL text. A condition
|
|
87
|
+
# that matches nothing reads no attribute, so it names no model.
|
|
88
|
+
#: () -> ScopeCondition
|
|
89
|
+
def self.nothing
|
|
90
|
+
new(nil, [:or, []])
|
|
91
|
+
end
|
|
92
|
+
private_class_method :nothing
|
|
93
|
+
|
|
66
94
|
# nil when the relation picks its members by conditions alone.
|
|
67
95
|
#: (untyped, untyped, untyped) -> ScopeRanking?
|
|
68
96
|
def self.ranking(relation, reflection, model_class)
|
|
@@ -116,10 +144,10 @@ module PaperTrailDiff
|
|
|
116
144
|
private_class_method :scoped_relation
|
|
117
145
|
|
|
118
146
|
# Some parts, such as the having clause `or` sets, may be present but
|
|
119
|
-
# empty.
|
|
120
|
-
#: (untyped) -> bool
|
|
121
|
-
def self.plain_relation?(relation)
|
|
122
|
-
extra = relation.values.except(*
|
|
147
|
+
# empty. `allowed` names the parts that may hold values.
|
|
148
|
+
#: (untyped, Array[Symbol]) -> bool
|
|
149
|
+
def self.plain_relation?(relation, allowed)
|
|
150
|
+
extra = relation.values.except(*allowed).values
|
|
123
151
|
extra.all? { |value| value.respond_to?(:empty?) && value.empty? }
|
|
124
152
|
end
|
|
125
153
|
private_class_method :plain_relation?
|
|
@@ -132,9 +160,18 @@ module PaperTrailDiff
|
|
|
132
160
|
freeze
|
|
133
161
|
end
|
|
134
162
|
|
|
163
|
+
# SQL admits a row only when its condition is true, not when it is
|
|
164
|
+
# unknown.
|
|
135
165
|
#: (Hash[String, untyped]) -> bool
|
|
136
166
|
def matches?(attributes)
|
|
137
|
-
evaluate(@predicate, attributes)
|
|
167
|
+
evaluate(@predicate, attributes) == true
|
|
168
|
+
end
|
|
169
|
+
|
|
170
|
+
# Whether no record can match, as for a relation `none` built.
|
|
171
|
+
#: () -> bool
|
|
172
|
+
def none?
|
|
173
|
+
operator, parts = @predicate
|
|
174
|
+
operator == :or && parts.empty?
|
|
138
175
|
end
|
|
139
176
|
|
|
140
177
|
# The members among records that are each the owner's by key: those that
|
|
@@ -152,36 +189,74 @@ module PaperTrailDiff
|
|
|
152
189
|
ranking ? ranking.call(records) : records
|
|
153
190
|
end
|
|
154
191
|
|
|
155
|
-
# SQL
|
|
156
|
-
# with nil,
|
|
192
|
+
# SQL's three values: a comparison with NULL is unknown (nil) rather than
|
|
193
|
+
# false, except an IS NULL or IS NOT NULL test, an equality with nil, which
|
|
194
|
+
# is always known. Unknown matters only under NOT, which leaves it
|
|
195
|
+
# unknown where false would become true.
|
|
157
196
|
COMPARISONS = {
|
|
158
|
-
eq: ->(value, expected) { value == expected },
|
|
159
|
-
not_eq: ->(value, expected) { !value.nil?
|
|
160
|
-
in: ->(value, expected) {
|
|
161
|
-
not_in: ->(value, expected) { !
|
|
197
|
+
eq: ->(value, expected) { expected.nil? || !value.nil? ? value == expected : nil },
|
|
198
|
+
not_eq: ->(value, expected) { expected.nil? || !value.nil? ? value != expected : nil },
|
|
199
|
+
in: ->(value, expected) { expected.include?(value) unless value.nil? },
|
|
200
|
+
not_in: ->(value, expected) { !expected.include?(value) unless value.nil? },
|
|
201
|
+
gt: ->(value, expected) { value > expected unless value.nil? },
|
|
202
|
+
gteq: ->(value, expected) { value >= expected unless value.nil? },
|
|
203
|
+
lt: ->(value, expected) { value < expected unless value.nil? },
|
|
204
|
+
lteq: ->(value, expected) { value <= expected unless value.nil? }
|
|
162
205
|
}.freeze
|
|
163
206
|
private_constant :COMPARISONS
|
|
164
207
|
|
|
208
|
+
# Comparisons that order values, which read them as ScopeRanking sorts.
|
|
209
|
+
ORDERED = %i[gt gteq lt lteq].freeze
|
|
210
|
+
private_constant :ORDERED
|
|
211
|
+
|
|
165
212
|
private
|
|
166
213
|
|
|
167
214
|
# @rbs @model_class: untyped
|
|
168
215
|
# @rbs @predicate: Array[untyped]
|
|
169
216
|
# @rbs @ranking: ScopeRanking?
|
|
170
217
|
|
|
171
|
-
|
|
218
|
+
# true, false, or nil for unknown.
|
|
219
|
+
#: (Array[untyped], Hash[String, untyped]) -> bool?
|
|
172
220
|
def evaluate(predicate, attributes)
|
|
173
221
|
operator, first, second = predicate
|
|
174
222
|
case operator
|
|
175
|
-
when :and then first.
|
|
176
|
-
when :or then first.
|
|
177
|
-
|
|
223
|
+
when :and then all(first.map { |part| evaluate(part, attributes) })
|
|
224
|
+
when :or then any(first.map { |part| evaluate(part, attributes) })
|
|
225
|
+
when :not then negate(evaluate(first, attributes))
|
|
226
|
+
else COMPARISONS.fetch(operator).call(stored(operator, first, attributes), second)
|
|
178
227
|
end
|
|
179
228
|
end
|
|
180
229
|
|
|
181
|
-
#
|
|
182
|
-
#: (
|
|
183
|
-
def
|
|
184
|
-
|
|
230
|
+
# False if any part is, otherwise unknown if any part is.
|
|
231
|
+
#: (Array[bool?]) -> bool?
|
|
232
|
+
def all(values)
|
|
233
|
+
return false if values.include?(false)
|
|
234
|
+
|
|
235
|
+
true unless values.include?(nil)
|
|
236
|
+
end
|
|
237
|
+
|
|
238
|
+
# True if any part is, otherwise unknown if any part is.
|
|
239
|
+
#: (Array[bool?]) -> bool?
|
|
240
|
+
def any(values)
|
|
241
|
+
return true if values.include?(true)
|
|
242
|
+
|
|
243
|
+
false unless values.include?(nil)
|
|
244
|
+
end
|
|
245
|
+
|
|
246
|
+
#: (bool?) -> bool?
|
|
247
|
+
def negate(value)
|
|
248
|
+
!value unless value.nil?
|
|
249
|
+
end
|
|
250
|
+
|
|
251
|
+
# The form the database holds, as the scope's own values were cast. An
|
|
252
|
+
# order reads the value the database sorts by instead: SQL Server holds a
|
|
253
|
+
# time or date in a wrapper that only compares for equality.
|
|
254
|
+
#: (Symbol, String, Hash[String, untyped]) -> untyped
|
|
255
|
+
def stored(operator, name, attributes)
|
|
256
|
+
value = attributes[name]
|
|
257
|
+
return ScopeRanking.sort_value(@model_class, name, value) if ORDERED.include?(operator)
|
|
258
|
+
|
|
259
|
+
@model_class.type_for_attribute(name).serialize(value)
|
|
185
260
|
end
|
|
186
261
|
|
|
187
262
|
# Builds each reflection's condition once per target class.
|
|
@@ -224,6 +299,7 @@ module PaperTrailDiff
|
|
|
224
299
|
when 'Arel::Nodes::And' then [:and, node.children.map { |child| call(child) }]
|
|
225
300
|
when 'Arel::Nodes::Or' then [:or, either(node).map { |child| call(child) }]
|
|
226
301
|
when 'Arel::Nodes::Grouping' then call(node.expr)
|
|
302
|
+
when 'Arel::Nodes::Not' then [:not, call(node.expr)]
|
|
227
303
|
else comparison(node)
|
|
228
304
|
end
|
|
229
305
|
end
|
|
@@ -246,13 +322,56 @@ module PaperTrailDiff
|
|
|
246
322
|
when 'Arel::Nodes::HomogeneousIn' then homogeneous_in(node)
|
|
247
323
|
when 'Arel::Nodes::In' then list(:in, node.left, values(node.right))
|
|
248
324
|
when 'Arel::Nodes::NotIn' then list(:not_in, node.left, values(node.right))
|
|
249
|
-
else
|
|
325
|
+
else range(node)
|
|
250
326
|
end
|
|
251
327
|
end
|
|
252
328
|
|
|
329
|
+
RANGES = { 'Arel::Nodes::GreaterThan' => :gt, 'Arel::Nodes::GreaterThanOrEqual' => :gteq,
|
|
330
|
+
'Arel::Nodes::LessThan' => :lt, 'Arel::Nodes::LessThanOrEqual' => :lteq }.freeze
|
|
331
|
+
private_constant :RANGES
|
|
332
|
+
|
|
333
|
+
# A range, as `where(created_at: 1.day.ago..)` writes it, on a column
|
|
334
|
+
# whose values sort in Ruby as the database sorts them.
|
|
335
|
+
#: (untyped) -> Array[untyped]
|
|
336
|
+
def range(node)
|
|
337
|
+
name = node.class.name
|
|
338
|
+
return between(node) if name == 'Arel::Nodes::Between'
|
|
339
|
+
|
|
340
|
+
operator = RANGES[name] or raise Unreadable
|
|
341
|
+
bound(operator, node.left, node.right)
|
|
342
|
+
end
|
|
343
|
+
|
|
344
|
+
#: (untyped) -> Array[untyped]
|
|
345
|
+
def between(node)
|
|
346
|
+
low, high = node.right.children
|
|
347
|
+
[:and, [bound(:gteq, node.left, low), bound(:lteq, node.left, high)]]
|
|
348
|
+
end
|
|
349
|
+
|
|
350
|
+
#: (Symbol, untyped, untyped) -> Array[untyped]
|
|
351
|
+
def bound(operator, attribute, node)
|
|
352
|
+
name = column(attribute, null_test: true)
|
|
353
|
+
boolean = :boolean.equal?(@model_class.type_for_attribute(name).type)
|
|
354
|
+
raise Unreadable unless ScopeRanking.orderable?(@model_class, name) && !boolean
|
|
355
|
+
|
|
356
|
+
expected = value(node)
|
|
357
|
+
raise Unreadable if expected.nil?
|
|
358
|
+
|
|
359
|
+
[operator, name, sort_value(name, expected)]
|
|
360
|
+
end
|
|
361
|
+
|
|
362
|
+
# A bound in the form the database holds, read back as the value the
|
|
363
|
+
# database sorts by. Reading it back unwraps what an adapter wraps.
|
|
364
|
+
#: (String, untyped) -> untyped
|
|
365
|
+
def sort_value(name, stored)
|
|
366
|
+
read = @model_class.type_for_attribute(name).deserialize(stored)
|
|
367
|
+
ScopeRanking.sort_value(@model_class, name, read)
|
|
368
|
+
end
|
|
369
|
+
|
|
370
|
+
# Whether a value is NULL compares alike on every type.
|
|
253
371
|
#: (Symbol, untyped) -> Array[untyped]
|
|
254
372
|
def binary(operator, node)
|
|
255
|
-
|
|
373
|
+
expected = value(node.right)
|
|
374
|
+
[operator, column(node.left, null_test: expected.nil?), expected]
|
|
256
375
|
end
|
|
257
376
|
|
|
258
377
|
#: (untyped) -> Array[untyped]
|
|
@@ -272,29 +391,35 @@ module PaperTrailDiff
|
|
|
272
391
|
end
|
|
273
392
|
|
|
274
393
|
# Ruby comparison stands in for SQL only on the record's own column of
|
|
275
|
-
# a type both compare alike.
|
|
276
|
-
|
|
277
|
-
|
|
394
|
+
# a type both compare alike. Whether a value is NULL, any column's
|
|
395
|
+
# type compares alike.
|
|
396
|
+
#: (untyped, ?null_test: bool) -> String
|
|
397
|
+
def column(attribute, null_test: false)
|
|
278
398
|
raise Unreadable unless ATTRIBUTE.eql?(attribute.class.name)
|
|
279
399
|
|
|
280
400
|
table = attribute.relation
|
|
281
401
|
raise Unreadable unless table.name == @model_class.table_name && table.table_alias.nil?
|
|
282
402
|
|
|
283
403
|
name = attribute.name
|
|
284
|
-
|
|
404
|
+
column = @model_class.columns_hash[name]
|
|
405
|
+
raise Unreadable unless column && (null_test || comparable?(name, column))
|
|
285
406
|
|
|
286
407
|
name
|
|
287
408
|
end
|
|
288
409
|
|
|
289
|
-
#: (String) -> bool
|
|
290
|
-
def comparable?(name)
|
|
291
|
-
column = @model_class.columns_hash[name]
|
|
410
|
+
#: (String, untyped) -> bool
|
|
411
|
+
def comparable?(name, column)
|
|
292
412
|
kinds = value_type(@model_class.type_for_attribute(name)).class.ancestors.map(&:name)
|
|
293
|
-
return false unless
|
|
294
|
-
|
|
413
|
+
return false unless VALUE_TYPES.intersect?(kinds)
|
|
414
|
+
|
|
415
|
+
!kinds.include?(TEXT_TYPE) || exact_text?(column)
|
|
416
|
+
end
|
|
295
417
|
|
|
418
|
+
# PostgreSQL's citext is text that compares without regard to case.
|
|
419
|
+
#: (untyped) -> bool
|
|
420
|
+
def exact_text?(column)
|
|
296
421
|
EXACT_TEXT_ADAPTERS.include?(@model_class.connection_db_config.adapter) &&
|
|
297
|
-
column.collation.nil?
|
|
422
|
+
column.collation.nil? && !column.sql_type.casecmp?('citext')
|
|
298
423
|
end
|
|
299
424
|
|
|
300
425
|
# An enum compares the values it stores, which its subtype describes. A
|
|
@@ -11,6 +11,9 @@ module PaperTrailDiff
|
|
|
11
11
|
DIRECTIONS = { 'Arel::Nodes::Ascending' => false, 'Arel::Nodes::Descending' => true }.freeze
|
|
12
12
|
ATTRIBUTE = 'Arel::Attributes::Attribute'
|
|
13
13
|
ENUM_TYPE = 'ActiveRecord::Enum::EnumType'
|
|
14
|
+
# Rails wraps a time-zone-aware attribute's type, by default every
|
|
15
|
+
# datetime's, in this delegator; the time it stores is the wrapped type's.
|
|
16
|
+
TIME_ZONE_TYPE = 'ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter'
|
|
14
17
|
# Integers, booleans and dates sort alike everywhere. Strings follow a
|
|
15
18
|
# collation, so they are not read.
|
|
16
19
|
ORDER_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
|
|
@@ -107,13 +110,29 @@ module PaperTrailDiff
|
|
|
107
110
|
def self.orderable?(model_class, name)
|
|
108
111
|
return false unless model_class.columns_hash.key?(name)
|
|
109
112
|
|
|
110
|
-
type = model_class.type_for_attribute(name)
|
|
111
|
-
type = type.subtype if ENUM_TYPE.eql?(type.class.name)
|
|
113
|
+
type = stored_type(model_class.type_for_attribute(name))
|
|
112
114
|
kinds = type.class.ancestors.map(&:name)
|
|
113
115
|
ORDER_TYPES.intersect?(kinds) ||
|
|
114
116
|
(kinds.include?(DATETIME_TYPE) && exact_time?(model_class, type))
|
|
115
117
|
end
|
|
116
|
-
|
|
118
|
+
|
|
119
|
+
# The value the database sorts by, as the column's type casts it. An enum
|
|
120
|
+
# sorts by the integer it stores; other types are compared cast, since an
|
|
121
|
+
# adapter may serialize a time or date as a wrapper, as SQL Server does.
|
|
122
|
+
#: (untyped, String, untyped) -> untyped
|
|
123
|
+
def self.sort_value(model_class, name, value)
|
|
124
|
+
type = model_class.type_for_attribute(name)
|
|
125
|
+
cast = type.cast(value)
|
|
126
|
+
ENUM_TYPE.eql?(type.class.name) ? type.serialize(cast) : cast
|
|
127
|
+
end
|
|
128
|
+
|
|
129
|
+
# The type of the value a column stores, under an enum or time zone wrapper.
|
|
130
|
+
#: (untyped) -> untyped
|
|
131
|
+
def self.stored_type(type)
|
|
132
|
+
type = type.subtype if ENUM_TYPE.eql?(type.class.name)
|
|
133
|
+
TIME_ZONE_TYPE.eql?(type.class.name) ? type.__getobj__ : type
|
|
134
|
+
end
|
|
135
|
+
private_class_method :stored_type
|
|
117
136
|
|
|
118
137
|
# Active Record truncates a time to its column's precision before writing
|
|
119
138
|
# it, so history holds the stored value when it keeps that many digits.
|
|
@@ -161,7 +180,7 @@ module PaperTrailDiff
|
|
|
161
180
|
#: (Hash[String, untyped]) -> Array[Array[Numeric]]
|
|
162
181
|
def sort_key(attributes)
|
|
163
182
|
@keys.map do |name, descending|
|
|
164
|
-
place = place(
|
|
183
|
+
place = place(ScopeRanking.sort_value(@model_class, name, attributes[name]))
|
|
165
184
|
descending ? place.map(&:-@) : place
|
|
166
185
|
end
|
|
167
186
|
end
|
|
@@ -182,15 +201,5 @@ module PaperTrailDiff
|
|
|
182
201
|
value = value.jd if value.respond_to?(:jd)
|
|
183
202
|
value.to_r
|
|
184
203
|
end
|
|
185
|
-
|
|
186
|
-
# The value the database sorts by, as the key's type casts it. An enum
|
|
187
|
-
# sorts by the integer it stores; other types are compared cast, since an
|
|
188
|
-
# adapter may serialize a time or date as a wrapper, as SQL Server does.
|
|
189
|
-
#: (String, Hash[String, untyped]) -> untyped
|
|
190
|
-
def stored(name, attributes)
|
|
191
|
-
type = @model_class.type_for_attribute(name)
|
|
192
|
-
value = type.cast(attributes[name])
|
|
193
|
-
ENUM_TYPE.eql?(type.class.name) ? type.serialize(value) : value
|
|
194
|
-
end
|
|
195
204
|
end
|
|
196
205
|
end
|
|
@@ -36,6 +36,17 @@ module PaperTrailDiff
|
|
|
36
36
|
freeze
|
|
37
37
|
end
|
|
38
38
|
|
|
39
|
+
# Each root's change rows, keyed as `analyses` is: the roots that still
|
|
40
|
+
# exist, then the deleted ones that have history to report. A deleted root
|
|
41
|
+
# without destroy history has no rows and is left out.
|
|
42
|
+
#: () -> Hash[Array[String], Array[ChangeRow]]
|
|
43
|
+
def change_rows
|
|
44
|
+
rows = {} #: Hash[Array[String], Array[ChangeRow]]
|
|
45
|
+
analyses.each { |identity, analysis| rows[identity] = analysis.change_rows }
|
|
46
|
+
deleted.each { |identity, analysis| rows[identity] = analysis.change_rows if analysis }
|
|
47
|
+
rows.freeze
|
|
48
|
+
end
|
|
49
|
+
|
|
39
50
|
# Two elements, not three: `roots` is reached by name so that existing
|
|
40
51
|
# destructuring keeps working.
|
|
41
52
|
#: () -> [Hash[Array[String], Analysis], Array[Array[String]]]
|