paper_trail_diff 0.16.0 → 0.17.1
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 +581 -1
- data/README.md +42 -7
- data/docs/architecture.md +7 -5
- data/docs/performance.md +86 -38
- data/docs/reference.md +309 -92
- data/docs/testing.md +240 -32
- data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
- data/lib/paper_trail_diff/activity_boundary.rb +55 -34
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +3 -13
- data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
- data/lib/paper_trail_diff/activity_event.rb +33 -21
- data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
- data/lib/paper_trail_diff/activity_event_route_finder.rb +29 -29
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -7
- data/lib/paper_trail_diff/activity_history.rb +90 -49
- data/lib/paper_trail_diff/activity_range.rb +9 -35
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +74 -40
- data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
- data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
- data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
- data/lib/paper_trail_diff/activity_timeline_builder.rb +194 -249
- data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
- data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
- data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
- data/lib/paper_trail_diff/activity_view.rb +22 -11
- data/lib/paper_trail_diff/analysis.rb +19 -5
- data/lib/paper_trail_diff/analysis_batch.rb +16 -58
- data/lib/paper_trail_diff/approximate_paths.rb +4 -8
- data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
- data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
- data/lib/paper_trail_diff/association_discovery.rb +1 -6
- data/lib/paper_trail_diff/association_key.rb +9 -6
- data/lib/paper_trail_diff/association_traversal.rb +49 -6
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
- data/lib/paper_trail_diff/batch_preload.rb +2 -12
- data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
- data/lib/paper_trail_diff/batched_root_analyzer.rb +16 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
- data/lib/paper_trail_diff/change_attribution.rb +329 -0
- data/lib/paper_trail_diff/change_row.rb +30 -10
- data/lib/paper_trail_diff/comparison_batch.rb +3 -4
- data/lib/paper_trail_diff/configuration.rb +1 -1
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -37
- data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
- data/lib/paper_trail_diff/deprecation.rb +4 -43
- data/lib/paper_trail_diff/diagnostics.rb +1 -2
- data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
- data/lib/paper_trail_diff/endpoint.rb +78 -44
- data/lib/paper_trail_diff/errors.rb +2 -9
- data/lib/paper_trail_diff/fallback_paths.rb +2 -5
- data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
- data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
- data/lib/paper_trail_diff/historical_filter.rb +40 -15
- data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
- data/lib/paper_trail_diff/instrumentation.rb +0 -8
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
- data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
- data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
- data/lib/paper_trail_diff/nested_comparator.rb +46 -19
- data/lib/paper_trail_diff/net_change.rb +276 -0
- data/lib/paper_trail_diff/own_window.rb +35 -0
- data/lib/paper_trail_diff/paper_trail_adapter.rb +40 -45
- data/lib/paper_trail_diff/prepared_activity_index.rb +197 -45
- data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
- data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
- data/lib/paper_trail_diff/prepared_history.rb +20 -31
- data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
- data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
- data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
- data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
- data/lib/paper_trail_diff/read_snapshot.rb +41 -19
- data/lib/paper_trail_diff/recorded_changes.rb +10 -11
- data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
- data/lib/paper_trail_diff/recorded_class.rb +14 -19
- data/lib/paper_trail_diff/recorded_columns.rb +33 -0
- data/lib/paper_trail_diff/root_version_plan.rb +20 -22
- data/lib/paper_trail_diff/root_version_selection.rb +39 -29
- data/lib/paper_trail_diff/scope_condition.rb +7 -17
- data/lib/paper_trail_diff/scope_ranking.rb +16 -22
- data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
- data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
- data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
- data/lib/paper_trail_diff/stored_json_values.rb +52 -0
- data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
- data/lib/paper_trail_diff/stored_values.rb +20 -0
- data/lib/paper_trail_diff/support.rb +185 -35
- data/lib/paper_trail_diff/time_of_day.rb +39 -0
- data/lib/paper_trail_diff/time_range.rb +37 -20
- data/lib/paper_trail_diff/time_version_range.rb +5 -10
- data/lib/paper_trail_diff/timeline_builder.rb +3 -3
- data/lib/paper_trail_diff/timeline_range.rb +18 -12
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
- data/lib/paper_trail_diff/total_order.rb +55 -0
- data/lib/paper_trail_diff/transaction_cut.rb +192 -91
- data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
- data/lib/paper_trail_diff/value_objects.rb +8 -4
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_association_candidate_scope.rb +27 -16
- data/lib/paper_trail_diff/version_boundary.rb +37 -21
- data/lib/paper_trail_diff/version_query.rb +25 -25
- data/lib/paper_trail_diff/version_range.rb +12 -16
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +32 -0
- data/lib/paper_trail_diff/version_table.rb +12 -8
- data/lib/paper_trail_diff.rb +28 -42
- data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
- data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +0 -5
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
- data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
- data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +11 -4
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -3
- data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +36 -2
- data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
- data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
- data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
- data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +121 -127
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
- data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
- data/sig/generated/paper_trail_diff/analysis.rbs +15 -6
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
- data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
- data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
- data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
- data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
- data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
- data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
- data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -8
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +11 -5
- data/sig/generated/paper_trail_diff/change_attribution.rbs +194 -0
- data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -12
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
- data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
- data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
- data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
- data/sig/generated/paper_trail_diff/errors.rbs +2 -11
- data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
- data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
- data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
- data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
- data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
- data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
- data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +9 -6
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +114 -14
- data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
- data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
- data/sig/generated/paper_trail_diff/prepared_history.rbs +9 -12
- data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
- data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
- data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
- data/sig/generated/paper_trail_diff/read_snapshot.rbs +27 -8
- data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
- data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
- data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
- data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
- data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
- data/sig/generated/paper_trail_diff/scope_condition.rbs +0 -2
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
- data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
- data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
- data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
- data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
- data/sig/generated/paper_trail_diff/support.rbs +120 -23
- data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
- data/sig/generated/paper_trail_diff/time_range.rbs +15 -8
- data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
- data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
- data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +111 -52
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
- data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
- data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +10 -9
- data/sig/generated/paper_trail_diff/version_boundary.rbs +15 -8
- data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
- data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +13 -0
- data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
- data/sig/generated/paper_trail_diff.rbs +16 -16
- metadata +28 -6
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
|
@@ -41,10 +41,23 @@ module PaperTrailDiff
|
|
|
41
41
|
# without destroy history has no rows and is left out.
|
|
42
42
|
#: () -> Hash[Array[String], Array[ChangeRow]]
|
|
43
43
|
def change_rows
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
44
|
+
each_root(&:change_rows)
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
# The analysis of one of `roots`, found from the record itself. The keys
|
|
48
|
+
# are its base class's name and its ID as a string, which a subclass or an
|
|
49
|
+
# integer ID gets wrong when built by hand. Raises KeyError for a record
|
|
50
|
+
# the selection did not load; a deleted root's analysis is in `deleted`.
|
|
51
|
+
#: (untyped) -> Analysis
|
|
52
|
+
def analysis_for(record)
|
|
53
|
+
analyses.fetch(Endpoint.identity(record))
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
# Each root's net changes, keyed as `change_rows` is; the block picks the
|
|
57
|
+
# rows to keep, as for Analysis#net_changes.
|
|
58
|
+
#: () ?{ (ChangeRow) -> boolish } -> Hash[Array[String], Array[NetChange]]
|
|
59
|
+
def net_changes(&keep)
|
|
60
|
+
each_root { |analysis| analysis.net_changes(&keep) }
|
|
48
61
|
end
|
|
49
62
|
|
|
50
63
|
# Two elements, not three: `roots` is reached by name so that existing
|
|
@@ -53,5 +66,15 @@ module PaperTrailDiff
|
|
|
53
66
|
def to_ary
|
|
54
67
|
[analyses, unreachable]
|
|
55
68
|
end
|
|
69
|
+
|
|
70
|
+
private
|
|
71
|
+
|
|
72
|
+
# What the block makes of each root's analysis: the roots that still
|
|
73
|
+
# exist, then the deleted ones that have history to report.
|
|
74
|
+
#: [T] () { (Analysis) -> T } -> Hash[Array[String], T]
|
|
75
|
+
def each_root(&block)
|
|
76
|
+
reported = deleted.filter_map { |identity, analysis| [identity, analysis] if analysis }
|
|
77
|
+
analyses.merge(reported.to_h).transform_values(&block).freeze
|
|
78
|
+
end
|
|
56
79
|
end
|
|
57
80
|
end
|
|
@@ -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?, ?version_scope: untyped) -> 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, ?traversal: AssociationTraversal?) -> 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, version_scope: nil
|
|
10
|
+
analyzer:, deleted_analyzer:, activity_tree: nil, version_scope: nil, traversal: 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,7 +17,8 @@ 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, version_scope: version_scope
|
|
20
|
+
activity_tree: activity_tree, version_scope: version_scope,
|
|
21
|
+
traversal: traversal
|
|
21
22
|
)
|
|
22
23
|
@deleted_filter = deleted_filter(scope, include_deleted)
|
|
23
24
|
@include_deleted = include_deleted
|
|
@@ -26,8 +26,9 @@ module PaperTrailDiff
|
|
|
26
26
|
# window. `where(status: 'published')` selects what is published now, which is
|
|
27
27
|
# not the same set as what was published while the window was open.
|
|
28
28
|
class ScopedRootSelection
|
|
29
|
-
|
|
30
|
-
|
|
29
|
+
MIN_PAGE_SIZE = 250
|
|
30
|
+
MAX_PAGE_SIZE = 2_000
|
|
31
|
+
private_constant :MIN_PAGE_SIZE, :MAX_PAGE_SIZE
|
|
31
32
|
|
|
32
33
|
# A plain class rather than Data.define, which arrived in Ruby 3.2 while this
|
|
33
34
|
# gem supports 3.1.
|
|
@@ -45,26 +46,23 @@ module PaperTrailDiff
|
|
|
45
46
|
|
|
46
47
|
# `activity_tree` names the association paths whose changes also select a
|
|
47
48
|
# root, as an activity analysis reports them. Without one, only a root's
|
|
48
|
-
# own versions select it. `version_scope` narrows which of
|
|
49
|
-
# as it narrows which are reported.
|
|
50
|
-
|
|
49
|
+
# own versions select it. `version_scope` narrows which of either count,
|
|
50
|
+
# as it narrows which are reported. `traversal` names the requested paths,
|
|
51
|
+
# which decide where a window's edges move (see TransactionCut).
|
|
52
|
+
#: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
|
|
51
53
|
def initialize(scope, time_range:, limit:, historical_filter: nil, # rubocop:disable Metrics/ParameterLists
|
|
52
54
|
max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil,
|
|
53
|
-
version_scope: nil)
|
|
55
|
+
version_scope: nil, traversal: nil)
|
|
54
56
|
@scope = normalize_scope(scope)
|
|
55
57
|
reject_unversioned!
|
|
56
58
|
@time_range = time_range
|
|
59
|
+
@path_types = traversal ? traversal.path_types(model) : [] #: Array[String]
|
|
57
60
|
@version_scope = VersionScopeFilter.validated(version_scope)
|
|
58
61
|
@limit = validate_limit(limit)
|
|
59
|
-
@related =
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
@historical_filter = unless historical_filter.nil?
|
|
64
|
-
HistoricalFilter.new(base_class, predicate: historical_filter,
|
|
65
|
-
time_range: time_range, limit: @limit,
|
|
66
|
-
max_versions: max_filter_versions)
|
|
67
|
-
end
|
|
62
|
+
@related = activity_tree && AssociationActivitySelection.new(
|
|
63
|
+
model, tree: activity_tree, time_range: time_range, version_scope: @version_scope
|
|
64
|
+
)
|
|
65
|
+
@historical_filter = historical_filter_for(historical_filter, max_filter_versions, traversal)
|
|
68
66
|
end
|
|
69
67
|
|
|
70
68
|
#: () -> Result
|
|
@@ -84,6 +82,7 @@ module PaperTrailDiff
|
|
|
84
82
|
# @rbs @historical_filter: untyped
|
|
85
83
|
# @rbs @related: AssociationActivitySelection?
|
|
86
84
|
# @rbs @version_scope: untyped
|
|
85
|
+
# @rbs @path_types: Array[String]
|
|
87
86
|
|
|
88
87
|
# Leaves the candidate set in the database. Plucking every root changed in
|
|
89
88
|
# the window would cost memory and a statement proportional to all activity
|
|
@@ -121,13 +120,22 @@ module PaperTrailDiff
|
|
|
121
120
|
live = ids_in(base_class.unscoped, candidates)
|
|
122
121
|
missing = candidates - live
|
|
123
122
|
if (filter = @historical_filter)
|
|
124
|
-
live = filter.call(
|
|
123
|
+
live = filter.call(relation_members(live))
|
|
125
124
|
missing = filter.call(missing, counted: false)
|
|
126
125
|
end
|
|
127
126
|
Result.new(records: selected_records([live]),
|
|
128
127
|
unreachable: missing.sort.map { |id| identity(id) }.freeze)
|
|
129
128
|
end
|
|
130
129
|
|
|
130
|
+
# The candidates the relation's conditions accept. A grouped relation's
|
|
131
|
+
# rows are groups, which a condition on one record cannot decide, and its
|
|
132
|
+
# aggregates read every candidate at once, so it keeps them all: the
|
|
133
|
+
# filter reads each, and the relation groups those that match.
|
|
134
|
+
#: (Array[String]) -> Array[String]
|
|
135
|
+
def relation_members(ids)
|
|
136
|
+
@scope.group_values.empty? ? ids_in(@scope.except(:order, :limit, :offset), ids).uniq : ids
|
|
137
|
+
end
|
|
138
|
+
|
|
131
139
|
# Comparing the two columns in SQL needs them to share a type: PostgreSQL
|
|
132
140
|
# rejects an integer key against a string item_id outright. A composite
|
|
133
141
|
# key names no single attribute, so it has no type and never matches.
|
|
@@ -155,15 +163,25 @@ module PaperTrailDiff
|
|
|
155
163
|
end
|
|
156
164
|
|
|
157
165
|
# Only the versions `version_scope` keeps select a root: one whose versions
|
|
158
|
-
# in the window it drops would have nothing to report.
|
|
166
|
+
# in the window it drops would have nothing to report. A version saved
|
|
167
|
+
# just before the window selects its root when TransactionCut moves the
|
|
168
|
+
# root's window back to take it in.
|
|
159
169
|
#: () -> untyped
|
|
160
170
|
def window_versions
|
|
161
|
-
relation =
|
|
162
|
-
range = @time_range
|
|
163
|
-
relation = range.scope(relation) if range
|
|
171
|
+
relation = TransactionCut.window_versions(model, @time_range, @path_types)
|
|
164
172
|
@version_scope ? @version_scope.call(relation) : relation
|
|
165
173
|
end
|
|
166
174
|
|
|
175
|
+
# The filter reads each candidate over the window its analysis will.
|
|
176
|
+
#: (untyped, Integer, AssociationTraversal?) -> HistoricalFilter?
|
|
177
|
+
def historical_filter_for(predicate, max_versions, traversal)
|
|
178
|
+
return if predicate.nil?
|
|
179
|
+
|
|
180
|
+
HistoricalFilter.new(base_class, predicate: predicate, time_range: @time_range,
|
|
181
|
+
limit: @limit, max_versions: max_versions,
|
|
182
|
+
windows: TransactionCut.reader(model, traversal))
|
|
183
|
+
end
|
|
184
|
+
|
|
167
185
|
# Accepts a model class as readily as a relation: `Article` and
|
|
168
186
|
# `Article.where(...)` both name a population, and `all` is what makes them
|
|
169
187
|
# the same kind of thing.
|
|
@@ -202,7 +220,7 @@ module PaperTrailDiff
|
|
|
202
220
|
|
|
203
221
|
#: (untyped, Array[String]) -> Array[String]
|
|
204
222
|
def ids_in(relation, candidates)
|
|
205
|
-
candidates.each_slice(
|
|
223
|
+
candidates.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
|
|
206
224
|
relation.where(primary_key => slice).pluck(primary_key).map(&:to_s)
|
|
207
225
|
end
|
|
208
226
|
end
|
|
@@ -221,18 +239,19 @@ module PaperTrailDiff
|
|
|
221
239
|
page = record_page(relation, consumed)
|
|
222
240
|
page.each { |record| records[record.id] ||= record }
|
|
223
241
|
reject_oversized!(records.length)
|
|
224
|
-
break if page.length <
|
|
242
|
+
break if page.length < page_size
|
|
225
243
|
|
|
226
244
|
consumed += page.length
|
|
227
245
|
end
|
|
228
246
|
records.values.freeze
|
|
229
247
|
end
|
|
230
248
|
|
|
249
|
+
# Pages are read by offset, so under a total order.
|
|
231
250
|
#: (Array[untyped]) -> untyped
|
|
232
251
|
def candidate_relation(candidates)
|
|
233
252
|
candidates.map do |ids|
|
|
234
253
|
conditions = { primary_key => ids } #: Hash[untyped, untyped]
|
|
235
|
-
|
|
254
|
+
TotalOrder.apply(@scope).where(conditions)
|
|
236
255
|
end.reduce(:or)
|
|
237
256
|
end
|
|
238
257
|
|
|
@@ -241,22 +260,26 @@ module PaperTrailDiff
|
|
|
241
260
|
count = page_limit(consumed)
|
|
242
261
|
return [] if count.zero?
|
|
243
262
|
|
|
244
|
-
relation.offset((@scope
|
|
245
|
-
end
|
|
246
|
-
|
|
247
|
-
# Preserve explicit ordering: SQL Server rejects duplicate ORDER BY columns,
|
|
248
|
-
# even when the extra ordering would only have served as a tie-breaker.
|
|
249
|
-
#: () -> untyped
|
|
250
|
-
def ordered_scope
|
|
251
|
-
return @scope unless @scope.order_values.empty?
|
|
252
|
-
|
|
253
|
-
@scope.order(primary_key => :asc)
|
|
263
|
+
relation.offset(Support.offset(@scope) + consumed).limit(count)
|
|
254
264
|
end
|
|
255
265
|
|
|
256
266
|
#: (Integer) -> Integer
|
|
257
267
|
def page_limit(consumed)
|
|
258
|
-
remaining = @scope
|
|
259
|
-
[remaining ? remaining - consumed :
|
|
268
|
+
remaining = Support.limit(@scope)
|
|
269
|
+
[remaining ? remaining - consumed : page_size, page_size].min
|
|
270
|
+
end
|
|
271
|
+
|
|
272
|
+
# Every page repeats the candidates, a list of ids or the subqueries that
|
|
273
|
+
# find them, and skips the rows read before it, so pages much smaller than
|
|
274
|
+
# the selection read the candidates many times over. More roots than
|
|
275
|
+
# `limit:` raise, so a page never needs more than one past it. A page
|
|
276
|
+
# holds at least 250 rows, for a relation whose joins repeat a record,
|
|
277
|
+
# and at most 2,000: SQL Server compiles a statement with its ids written
|
|
278
|
+
# in, and one that listed 20,000 and returned them all outlasted the
|
|
279
|
+
# adapter's default timeout of 5 seconds.
|
|
280
|
+
#: () -> Integer
|
|
281
|
+
def page_size
|
|
282
|
+
(@limit + 1).clamp(MIN_PAGE_SIZE, MAX_PAGE_SIZE)
|
|
260
283
|
end
|
|
261
284
|
|
|
262
285
|
#: (Integer) -> void
|
|
@@ -268,14 +291,10 @@ module PaperTrailDiff
|
|
|
268
291
|
'relation, or raise limit: to the page size you intend to analyze'
|
|
269
292
|
end
|
|
270
293
|
|
|
294
|
+
# Keyed as Endpoint.identity keys the record, which the analyses use.
|
|
271
295
|
#: (String) -> Array[String]
|
|
272
296
|
def identity(id)
|
|
273
|
-
|
|
274
|
-
end
|
|
275
|
-
|
|
276
|
-
#: () -> String
|
|
277
|
-
def item_type
|
|
278
|
-
base_class.name
|
|
297
|
+
Support.record_identity(model, id).freeze
|
|
279
298
|
end
|
|
280
299
|
|
|
281
300
|
# A relation delegates class methods to its model, so every mutation here,
|
|
@@ -56,6 +56,7 @@ module PaperTrailDiff
|
|
|
56
56
|
@pool = pool
|
|
57
57
|
@structural_columns = {} #: Hash[String, Array[String]]
|
|
58
58
|
@excluded_attributes = {} #: Hash[Array[untyped], Array[String?]]
|
|
59
|
+
@leaves = {} #: Hash[String, Hash[PreparedRecordState, RecordSnapshot]]
|
|
59
60
|
end
|
|
60
61
|
|
|
61
62
|
#: (untyped, reifier: untyped) -> RecordSnapshot?
|
|
@@ -90,8 +91,22 @@ module PaperTrailDiff
|
|
|
90
91
|
end
|
|
91
92
|
|
|
92
93
|
# Same exclusions as AR normalization, applied to an already typed state.
|
|
94
|
+
# A state without associations is normalized once at each path: the
|
|
95
|
+
# same state is read again at every boundary it spans.
|
|
93
96
|
#: (PreparedRecordState, tree: AssociationTree, path: String, ?incoming: untyped, ?associations: snapshot_associations) -> RecordSnapshot
|
|
94
97
|
def from_state(state, tree:, path:, incoming: nil, associations: {})
|
|
98
|
+
unless associations.empty?
|
|
99
|
+
return snapshot_from_state(state, tree, path, incoming, associations)
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
leaves = @leaves[path] ||= {}
|
|
103
|
+
leaves[state] ||= snapshot_from_state(state, tree, path, incoming, associations)
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
private
|
|
107
|
+
|
|
108
|
+
#: (PreparedRecordState, AssociationTree, String, untyped, snapshot_associations) -> RecordSnapshot
|
|
109
|
+
def snapshot_from_state(state, tree, path, incoming, associations)
|
|
95
110
|
model = state.model_class
|
|
96
111
|
@structural_columns[path] ||= @traversal.incoming_relationship_columns(incoming) if incoming
|
|
97
112
|
reflections = @traversal.reflections_for(model, tree, path: path)
|
|
@@ -104,8 +119,6 @@ module PaperTrailDiff
|
|
|
104
119
|
pool_state(path, snapshot)
|
|
105
120
|
end
|
|
106
121
|
|
|
107
|
-
private
|
|
108
|
-
|
|
109
122
|
# The id a live record of the same row reports: one value, or one per
|
|
110
123
|
# column of a composite key.
|
|
111
124
|
#: (untyped, PreparedRecordState) -> untyped
|
|
@@ -125,6 +138,7 @@ module PaperTrailDiff
|
|
|
125
138
|
# @rbs @pool: SnapshotPool
|
|
126
139
|
# @rbs @structural_columns: Hash[String, Array[String]]
|
|
127
140
|
# @rbs @excluded_attributes: Hash[Array[untyped], Array[String?]]
|
|
141
|
+
# @rbs @leaves: Hash[String, Hash[PreparedRecordState, RecordSnapshot]]
|
|
128
142
|
|
|
129
143
|
#: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot
|
|
130
144
|
def normalize_record(record, tree, path, reifier, reflections)
|
|
@@ -141,7 +155,7 @@ module PaperTrailDiff
|
|
|
141
155
|
def normalized_attributes(record, reflections, path)
|
|
142
156
|
attributes = record.attributes
|
|
143
157
|
excluded_attributes(record, reflections, path).each { |name| attributes.delete(name) }
|
|
144
|
-
|
|
158
|
+
StoredValues.apply(record.class, attributes)
|
|
145
159
|
end
|
|
146
160
|
|
|
147
161
|
# Every input is fixed for one model class at one selected path, and the
|
|
@@ -222,6 +236,7 @@ module PaperTrailDiff
|
|
|
222
236
|
def normalize_children(records, tree, path, reifier)
|
|
223
237
|
reflections_by_class = {} #: Hash[untyped, Array[untyped]]
|
|
224
238
|
records.map do |child|
|
|
239
|
+
Support.with_recorded_times(child)
|
|
225
240
|
reflections = reflections_by_class[child.class] ||= reflections_for(child, tree, path)
|
|
226
241
|
reifier.reify(child, reflections) unless reflections.empty?
|
|
227
242
|
normalize_record(child, tree, path, reifier, reflections)
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
# rbs_inline: enabled
|
|
3
|
+
|
|
4
|
+
module PaperTrailDiff
|
|
5
|
+
# Reads values in the form JSON history gives them back.
|
|
6
|
+
#
|
|
7
|
+
# A `json` or `jsonb` object column stores a record's attributes as they
|
|
8
|
+
# are, without PaperTrail's attribute serializer, so a `serialize`d value
|
|
9
|
+
# comes back as JSON writes it: keys as strings, and dates, times and
|
|
10
|
+
# symbols inside it as strings, which its type does not cast back.
|
|
11
|
+
# PaperTrail's JSON serializer stores a binary value as `{"value" => bytes}`,
|
|
12
|
+
# which its type does not cast back either. Compared as they are, the live
|
|
13
|
+
# row and every version would differ though nothing was edited. So every
|
|
14
|
+
# side is read in one form: a `serialize`d value as JSON writes it, and a
|
|
15
|
+
# binary value as its bytes. Both leave a value read from history as it is.
|
|
16
|
+
module StoredJsonValues
|
|
17
|
+
SERIALIZED_TYPE = 'ActiveRecord::Type::Serialized'
|
|
18
|
+
BINARY_TYPE = 'ActiveModel::Type::Binary'
|
|
19
|
+
BINARY_KEYS = ['value'].freeze
|
|
20
|
+
private_constant :SERIALIZED_TYPE, :BINARY_TYPE, :BINARY_KEYS
|
|
21
|
+
|
|
22
|
+
# For a model whose history is JSON, which StoredTimePrecision.digits
|
|
23
|
+
# tells: a `json` or `jsonb` object column, or the JSON serializer.
|
|
24
|
+
#: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
|
|
25
|
+
def self.apply(model_class, attributes)
|
|
26
|
+
if StoredTimePrecision.json_column?(model_class.paper_trail.version_class, 'object')
|
|
27
|
+
convert(model_class, attributes, SERIALIZED_TYPE, &:as_json)
|
|
28
|
+
else
|
|
29
|
+
convert(model_class, attributes, BINARY_TYPE) { |value| bytes(value) }
|
|
30
|
+
end
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# The attributes with the value of each of this type converted. An
|
|
34
|
+
# adapter's type can be a subclass, as PostgreSQL's `bytea` is of binary.
|
|
35
|
+
#: (untyped, Hash[untyped, untyped], String) { (untyped) -> untyped } -> Hash[untyped, untyped]
|
|
36
|
+
def self.convert(model_class, attributes, type_name)
|
|
37
|
+
type = Support.constant(type_name)
|
|
38
|
+
attributes.to_h do |name, value|
|
|
39
|
+
[name, model_class.type_for_attribute(name).is_a?(type) ? yield(value) : value]
|
|
40
|
+
end
|
|
41
|
+
end
|
|
42
|
+
private_class_method :convert
|
|
43
|
+
|
|
44
|
+
#: (untyped) -> untyped
|
|
45
|
+
def self.bytes(value)
|
|
46
|
+
return value unless value.instance_of?(Hash) && value.keys == BINARY_KEYS
|
|
47
|
+
|
|
48
|
+
value.fetch('value').b
|
|
49
|
+
end
|
|
50
|
+
private_class_method :bytes
|
|
51
|
+
end
|
|
52
|
+
end
|
|
@@ -17,52 +17,64 @@ module PaperTrailDiff
|
|
|
17
17
|
JSON_COLUMN_TYPES = %i[json jsonb].freeze
|
|
18
18
|
private_constant :NANOSECOND_DIGITS, :JSON_COLUMN_TYPES
|
|
19
19
|
|
|
20
|
-
module_function
|
|
21
|
-
|
|
22
20
|
# Fractional digits a model's history keeps for times, or nil when the
|
|
23
21
|
# history is stored losslessly.
|
|
24
22
|
#: (untyped) -> Integer?
|
|
25
|
-
def digits(model_class)
|
|
23
|
+
def self.digits(model_class)
|
|
26
24
|
return unless Support.versioned?(model_class)
|
|
27
25
|
return unless json_history?(model_class.paper_trail.version_class)
|
|
28
26
|
|
|
29
|
-
|
|
30
|
-
active_support.const_get(:JSON).const_get(:Encoding).time_precision
|
|
27
|
+
json_time_precision
|
|
31
28
|
end
|
|
32
29
|
|
|
33
30
|
#: (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
|
|
34
|
-
def apply(attributes, digits)
|
|
31
|
+
def self.apply(attributes, digits)
|
|
35
32
|
return attributes unless digits
|
|
36
33
|
|
|
37
34
|
attributes.transform_values { |value| truncate(value, digits) }
|
|
38
35
|
end
|
|
39
36
|
|
|
37
|
+
# From nine digits on, the step is one nanosecond or a fraction of one, so
|
|
38
|
+
# nothing is cut.
|
|
40
39
|
#: (untyped, Integer) -> untyped
|
|
41
|
-
def truncate(value, digits)
|
|
42
|
-
return value unless value.is_a?(Time)
|
|
40
|
+
def self.truncate(value, digits)
|
|
41
|
+
return value unless value.is_a?(Time)
|
|
43
42
|
|
|
44
43
|
# ActiveSupport's Time#change, which also serves TimeWithZone.
|
|
45
44
|
time = value #: untyped
|
|
46
|
-
|
|
47
|
-
remainder = time.nsec % step
|
|
45
|
+
remainder = time.nsec % (10**(NANOSECOND_DIGITS - digits))
|
|
48
46
|
remainder.zero? ? time : time.change(nsec: time.nsec - remainder)
|
|
49
47
|
end
|
|
50
48
|
|
|
51
49
|
#: (untyped) -> bool
|
|
52
|
-
def json_history?(version_class)
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
JSON_COLUMN_TYPES.include?(columns[name]&.type)
|
|
56
|
-
end
|
|
57
|
-
json_column || json_serializer?
|
|
50
|
+
def self.json_history?(version_class)
|
|
51
|
+
%w[object object_changes].any? { |name| json_column?(version_class, name) } ||
|
|
52
|
+
json_serializer?
|
|
58
53
|
end
|
|
59
54
|
private_class_method :json_history?
|
|
60
55
|
|
|
56
|
+
# Whether the version table keeps this column as `json` or `jsonb`, which
|
|
57
|
+
# PaperTrail writes without its serializer.
|
|
58
|
+
#: (untyped, String) -> bool
|
|
59
|
+
def self.json_column?(version_class, name)
|
|
60
|
+
JSON_COLUMN_TYPES.include?(version_class.columns_hash[name]&.type)
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
# mutant:disable - Every mutation that survives here reads the same
|
|
64
|
+
# constant another way: from this module rather than Object, or with `::`.
|
|
65
|
+
#: () -> Integer
|
|
66
|
+
def self.json_time_precision
|
|
67
|
+
active_support = Object.const_get(:ActiveSupport) #: untyped
|
|
68
|
+
active_support.const_get(:JSON).const_get(:Encoding).time_precision
|
|
69
|
+
end
|
|
70
|
+
private_class_method :json_time_precision
|
|
71
|
+
|
|
72
|
+
# Whether PaperTrail writes history with its JSON serializer.
|
|
73
|
+
# mutant:disable - As for json_time_precision.
|
|
61
74
|
#: () -> bool
|
|
62
|
-
def json_serializer?
|
|
75
|
+
def self.json_serializer?
|
|
63
76
|
paper_trail = Object.const_get(:PaperTrail) #: untyped
|
|
64
77
|
paper_trail.serializer.equal?(paper_trail.const_get(:Serializers).const_get(:JSON))
|
|
65
78
|
end
|
|
66
|
-
private_class_method :json_serializer?
|
|
67
79
|
end
|
|
68
80
|
end
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
# rbs_inline: enabled
|
|
3
|
+
|
|
4
|
+
module PaperTrailDiff
|
|
5
|
+
# Reads a model's attribute values in the one form every account of them
|
|
6
|
+
# shares: a version decoded from history, the current row, and the changes
|
|
7
|
+
# a version recorded. Each would otherwise differ where nothing was edited.
|
|
8
|
+
# TimeOfDay puts a time of day on one date, and for JSON history,
|
|
9
|
+
# StoredJsonValues and StoredTimePrecision read values as JSON stored them.
|
|
10
|
+
module StoredValues
|
|
11
|
+
#: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
|
|
12
|
+
def self.apply(model_class, attributes)
|
|
13
|
+
attributes = TimeOfDay.apply(model_class, attributes)
|
|
14
|
+
digits = StoredTimePrecision.digits(model_class)
|
|
15
|
+
return attributes unless digits
|
|
16
|
+
|
|
17
|
+
StoredTimePrecision.apply(StoredJsonValues.apply(model_class, attributes), digits)
|
|
18
|
+
end
|
|
19
|
+
end
|
|
20
|
+
end
|