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
|
@@ -4,10 +4,10 @@
|
|
|
4
4
|
module PaperTrailDiff
|
|
5
5
|
# Selects both populations and checks their shared ceiling before analysis.
|
|
6
6
|
class ScopedAnalysisBuilder
|
|
7
|
-
#: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?) -> void
|
|
7
|
+
#: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
|
|
8
8
|
def initialize( # rubocop:disable Metrics/ParameterLists
|
|
9
9
|
scope, limit:, within:, historical_filter:, max_filter_versions:, include_deleted:,
|
|
10
|
-
analyzer:, deleted_analyzer:, activity_tree: nil
|
|
10
|
+
analyzer:, deleted_analyzer:, activity_tree: nil, version_scope: nil
|
|
11
11
|
)
|
|
12
12
|
raise ConfigurationError, 'limit: is required when selecting roots by scope' if limit.nil?
|
|
13
13
|
unless [true, false].include?(include_deleted)
|
|
@@ -17,10 +17,11 @@ module PaperTrailDiff
|
|
|
17
17
|
@selection = ScopedRootSelection.new(
|
|
18
18
|
scope, limit: limit, time_range: within.nil? ? nil : TimeRange.new(within),
|
|
19
19
|
historical_filter: historical_filter, max_filter_versions: max_filter_versions,
|
|
20
|
-
activity_tree: activity_tree
|
|
20
|
+
activity_tree: activity_tree, version_scope: version_scope
|
|
21
21
|
)
|
|
22
|
-
@
|
|
22
|
+
@deleted_filter = deleted_filter(scope, include_deleted)
|
|
23
23
|
@include_deleted = include_deleted
|
|
24
|
+
@limit = limit
|
|
24
25
|
@analyzer = analyzer
|
|
25
26
|
@deleted_analyzer = deleted_analyzer
|
|
26
27
|
end
|
|
@@ -28,20 +29,37 @@ module PaperTrailDiff
|
|
|
28
29
|
#: () -> ScopedAnalysis
|
|
29
30
|
def call
|
|
30
31
|
selection = @selection.call
|
|
31
|
-
|
|
32
|
+
unreachable = @deleted_filter&.call(selection.unreachable) || selection.unreachable
|
|
33
|
+
return analysis(selection, unreachable, {}) unless @include_deleted
|
|
34
|
+
|
|
35
|
+
if selection.records.length + unreachable.length > @limit
|
|
32
36
|
raise BatchLimitExceededError, 'include_deleted: live and missing roots exceed limit:'
|
|
33
37
|
end
|
|
34
38
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
39
|
+
analysis(selection, unreachable, @deleted_analyzer.call(unreachable))
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
private
|
|
43
|
+
|
|
44
|
+
# Without the option, the deleted roots are still tested when the
|
|
45
|
+
# relation can be read, so that another selection's are not listed.
|
|
46
|
+
#: (untyped, bool) -> DeletedRootFilter?
|
|
47
|
+
def deleted_filter(scope, include_deleted)
|
|
48
|
+
return DeletedRootFilter.new(scope.all) if include_deleted
|
|
49
|
+
|
|
50
|
+
DeletedRootFilter.readable(scope.all)
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
#: (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
|
|
54
|
+
def analysis(selection, unreachable, deleted)
|
|
55
|
+
ScopedAnalysis.new(analyses: @analyzer.call(selection.records), roots: selection.records,
|
|
56
|
+
unreachable: unreachable, deleted: deleted)
|
|
40
57
|
end
|
|
41
58
|
|
|
42
59
|
# @rbs @selection: ScopedRootSelection
|
|
43
|
-
# @rbs @
|
|
60
|
+
# @rbs @deleted_filter: DeletedRootFilter?
|
|
44
61
|
# @rbs @include_deleted: bool
|
|
62
|
+
# @rbs @limit: Integer
|
|
45
63
|
# @rbs @analyzer: untyped
|
|
46
64
|
# @rbs @deleted_analyzer: untyped
|
|
47
65
|
end
|
|
@@ -45,13 +45,16 @@ module PaperTrailDiff
|
|
|
45
45
|
|
|
46
46
|
# `activity_tree` names the association paths whose changes also select a
|
|
47
47
|
# root, as an activity analysis reports them. Without one, only a root's
|
|
48
|
-
# own versions select it.
|
|
49
|
-
|
|
48
|
+
# own versions select it. `version_scope` narrows which of those count,
|
|
49
|
+
# as it narrows which are reported.
|
|
50
|
+
#: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
|
|
50
51
|
def initialize(scope, time_range:, limit:, historical_filter: nil, # rubocop:disable Metrics/ParameterLists
|
|
51
|
-
max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil
|
|
52
|
+
max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil,
|
|
53
|
+
version_scope: nil)
|
|
52
54
|
@scope = normalize_scope(scope)
|
|
53
55
|
reject_unversioned!
|
|
54
56
|
@time_range = time_range
|
|
57
|
+
@version_scope = VersionScopeFilter.validated(version_scope)
|
|
55
58
|
@limit = validate_limit(limit)
|
|
56
59
|
@related = if activity_tree
|
|
57
60
|
AssociationActivitySelection.new(model, tree: activity_tree,
|
|
@@ -80,6 +83,7 @@ module PaperTrailDiff
|
|
|
80
83
|
# @rbs @limit: Integer
|
|
81
84
|
# @rbs @historical_filter: untyped
|
|
82
85
|
# @rbs @related: AssociationActivitySelection?
|
|
86
|
+
# @rbs @version_scope: untyped
|
|
83
87
|
|
|
84
88
|
# Leaves the candidate set in the database. Plucking every root changed in
|
|
85
89
|
# the window would cost memory and a statement proportional to all activity
|
|
@@ -106,14 +110,22 @@ module PaperTrailDiff
|
|
|
106
110
|
matching if matching.length == related.length
|
|
107
111
|
end
|
|
108
112
|
|
|
113
|
+
# Which candidates still have a row is asked without the relation's
|
|
114
|
+
# conditions, so that "filtered out" and "no longer exists" stay
|
|
115
|
+
# separable. A filter then reads the history of the relation's records
|
|
116
|
+
# only, whose order and page choose among those that match, and of the
|
|
117
|
+
# deleted ones, which no relation can test. Those it lists, as without a
|
|
118
|
+
# filter, but does not count toward `limit:`.
|
|
109
119
|
#: (Array[String]) -> Result
|
|
110
120
|
def plucked_selection(candidates)
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
121
|
+
live = ids_in(base_class.unscoped, candidates)
|
|
122
|
+
missing = candidates - live
|
|
123
|
+
if (filter = @historical_filter)
|
|
124
|
+
live = filter.call(ids_in(@scope.except(:order, :limit, :offset), live).uniq)
|
|
125
|
+
missing = filter.call(missing, counted: false)
|
|
126
|
+
end
|
|
127
|
+
Result.new(records: selected_records([live]),
|
|
128
|
+
unreachable: missing.sort.map { |id| identity(id) }.freeze)
|
|
117
129
|
end
|
|
118
130
|
|
|
119
131
|
# Comparing the two columns in SQL needs them to share a type: PostgreSQL
|
|
@@ -142,11 +154,14 @@ module PaperTrailDiff
|
|
|
142
154
|
window_versions.where.not(item_id: base_class.unscoped).distinct.pluck(:item_id).map(&:to_s)
|
|
143
155
|
end
|
|
144
156
|
|
|
157
|
+
# Only the versions `version_scope` keeps select a root: one whose versions
|
|
158
|
+
# in the window it drops would have nothing to report.
|
|
145
159
|
#: () -> untyped
|
|
146
160
|
def window_versions
|
|
147
|
-
relation =
|
|
161
|
+
relation = VersionQuery.for_model(model)
|
|
148
162
|
range = @time_range
|
|
149
|
-
|
|
163
|
+
relation = range.scope(relation) if range
|
|
164
|
+
@version_scope ? @version_scope.call(relation) : relation
|
|
150
165
|
end
|
|
151
166
|
|
|
152
167
|
# Accepts a model class as readily as a relation: `Article` and
|
|
@@ -185,12 +200,10 @@ module PaperTrailDiff
|
|
|
185
200
|
window_versions.distinct.pluck(:item_id).map(&:to_s)
|
|
186
201
|
end
|
|
187
202
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
#: (Array[String]) -> Array[String]
|
|
191
|
-
def live_ids(candidates)
|
|
203
|
+
#: (untyped, Array[String]) -> Array[String]
|
|
204
|
+
def ids_in(relation, candidates)
|
|
192
205
|
candidates.each_slice(PAGE_SIZE).flat_map do |slice|
|
|
193
|
-
|
|
206
|
+
relation.where(primary_key => slice).pluck(primary_key).map(&:to_s)
|
|
194
207
|
end
|
|
195
208
|
end
|
|
196
209
|
|
|
@@ -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)
|
|
@@ -44,6 +44,20 @@ 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)
|
|
@@ -70,11 +84,24 @@ module PaperTrailDiff
|
|
|
70
84
|
#: (Array[untyped]) -> Array[untyped]?
|
|
71
85
|
def ambiguous_pair(sorted)
|
|
72
86
|
sorted.each_cons(2).find do |left, right|
|
|
73
|
-
left.created_at == right.created_at &&
|
|
74
|
-
!(sequential_id?(left.id) && sequential_id?(right.id))
|
|
87
|
+
left.created_at == right.created_at && !orderable_tie?(left, right)
|
|
75
88
|
end
|
|
76
89
|
end
|
|
77
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
|
+
|
|
78
105
|
# Versions sharing a timestamp, whether or not their ids order them. PT-AT
|
|
79
106
|
# indexes association membership per version but resolves it by timestamp,
|
|
80
107
|
# so association state cannot be told apart across such a pair even when the
|
|
@@ -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
|
|
@@ -35,7 +39,13 @@ module PaperTrailDiff
|
|
|
35
39
|
|
|
36
40
|
#: (untyped) -> untyped
|
|
37
41
|
def scope(relation)
|
|
38
|
-
relation.where(created_at:
|
|
42
|
+
relation.where(created_at: to_range)
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
# The window as a Ruby range, its end included or left out as given.
|
|
46
|
+
#: () -> Range[Time]
|
|
47
|
+
def to_range
|
|
48
|
+
exclude_end? ? (begin_time...end_time) : (begin_time..end_time)
|
|
39
49
|
end
|
|
40
50
|
|
|
41
51
|
#: (untyped) -> untyped
|
|
@@ -67,11 +77,6 @@ module PaperTrailDiff
|
|
|
67
77
|
exclude_end? ? column.gteq(end_time) : column.gt(end_time)
|
|
68
78
|
end
|
|
69
79
|
|
|
70
|
-
#: () -> Range[Time]
|
|
71
|
-
def query_range
|
|
72
|
-
exclude_end? ? (begin_time...end_time) : (begin_time..end_time)
|
|
73
|
-
end
|
|
74
|
-
|
|
75
80
|
#: (untyped, boundary: Symbol) -> Time
|
|
76
81
|
def coerce_time(value, boundary:)
|
|
77
82
|
time_value(value).getutc.freeze
|
|
@@ -79,16 +84,34 @@ module PaperTrailDiff
|
|
|
79
84
|
raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
|
|
80
85
|
end
|
|
81
86
|
|
|
82
|
-
#
|
|
83
|
-
#
|
|
84
|
-
#
|
|
85
|
-
|
|
86
|
-
#: (untyped) -> Time
|
|
87
|
+
# Anything else names its instant, and `getutc` reads it without
|
|
88
|
+
# `to_time`, which Active Support 8.0 and older warn will change on a
|
|
89
|
+
# zoned time, and without changing the caller's own value as `utc` does.
|
|
90
|
+
#: (untyped) -> untyped
|
|
87
91
|
def time_value(value)
|
|
88
|
-
return value if value.is_a?(
|
|
92
|
+
return zone.parse(value) || raise(ArgumentError) if value.is_a?(String)
|
|
93
|
+
return zone.local(value.year, value.month, value.day) if calendar_date?(value)
|
|
94
|
+
|
|
95
|
+
value
|
|
96
|
+
end
|
|
97
|
+
|
|
98
|
+
# An inclusive date end runs through the day: to the next one's start.
|
|
99
|
+
#: (Range[untyped]) -> untyped
|
|
100
|
+
def end_value(range)
|
|
101
|
+
last = range.end
|
|
102
|
+
calendar_date?(last) && !range.exclude_end? ? last.next_day : last
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
# A DateTime is a Date too, but names its instant.
|
|
106
|
+
#: (untyped) -> bool
|
|
107
|
+
def calendar_date?(value)
|
|
108
|
+
value.instance_of?(Date)
|
|
109
|
+
end
|
|
89
110
|
|
|
90
|
-
|
|
91
|
-
|
|
111
|
+
#: () -> untyped
|
|
112
|
+
def zone
|
|
113
|
+
time = Time #: untyped
|
|
114
|
+
time.zone || time.find_zone!('UTC')
|
|
92
115
|
end
|
|
93
116
|
|
|
94
117
|
#: () -> void
|
|
@@ -24,6 +24,12 @@ module PaperTrailDiff
|
|
|
24
24
|
steps
|
|
25
25
|
end
|
|
26
26
|
|
|
27
|
+
# The window the range covers once its edges have moved to transactions.
|
|
28
|
+
#: () -> TimeRange?
|
|
29
|
+
def window
|
|
30
|
+
@range.time_range
|
|
31
|
+
end
|
|
32
|
+
|
|
27
33
|
#: () -> Analysis
|
|
28
34
|
def analyze
|
|
29
35
|
steps, first_snapshot, last_snapshot = compare_history(selected_versions)
|
|
@@ -46,21 +52,21 @@ module PaperTrailDiff
|
|
|
46
52
|
return empty_history if plan.empty?
|
|
47
53
|
|
|
48
54
|
versions = plan.versions
|
|
49
|
-
@snapshotter.prepare(@record, versions)
|
|
50
|
-
steps = build_steps(plan)
|
|
51
|
-
final = plan.closes_on_destroy ? nil :
|
|
52
|
-
[steps,
|
|
55
|
+
snapshots = @snapshotter.prepare(@record, versions)
|
|
56
|
+
steps = build_steps(plan, snapshots)
|
|
57
|
+
final = plan.closes_on_destroy ? nil : snapshots.call(plan.final_endpoint)
|
|
58
|
+
[steps, snapshots.call(versions.first), final]
|
|
53
59
|
end
|
|
54
60
|
|
|
55
|
-
#: (RootVersionPlan) -> Array[Step]
|
|
56
|
-
def build_steps(plan)
|
|
61
|
+
#: (RootVersionPlan, untyped) -> Array[Step]
|
|
62
|
+
def build_steps(plan, snapshots)
|
|
57
63
|
captured_at = Time.now.utc if plan.closing_record
|
|
58
64
|
plan.steps.map do |from_endpoint, to_endpoint|
|
|
59
65
|
Step.new(
|
|
60
66
|
from_version: from_endpoint,
|
|
61
67
|
to_version: to_endpoint,
|
|
62
68
|
captured_at: captured_at,
|
|
63
|
-
diff: Engine.compare(
|
|
69
|
+
diff: Engine.compare(snapshots.call(from_endpoint), snapshots.call(to_endpoint))
|
|
64
70
|
)
|
|
65
71
|
end.freeze
|
|
66
72
|
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?]
|