paper_trail_diff 0.17.1 → 0.18.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.
Files changed (215) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +661 -0
  3. data/QUICKSTART.md +12 -14
  4. data/README.md +32 -30
  5. data/docs/architecture.md +65 -29
  6. data/docs/performance.md +161 -46
  7. data/docs/reference.md +495 -394
  8. data/docs/testing.md +9 -15
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +15 -6
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
  14. data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
  15. data/lib/paper_trail_diff/activity_event.rb +53 -34
  16. data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
  17. data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
  18. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
  19. data/lib/paper_trail_diff/activity_history.rb +28 -34
  20. data/lib/paper_trail_diff/activity_relationship.rb +3 -26
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
  25. data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
  27. data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
  28. data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
  29. data/lib/paper_trail_diff/activity_view.rb +2 -0
  30. data/lib/paper_trail_diff/analysis.rb +6 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +21 -17
  32. data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
  33. data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
  34. data/lib/paper_trail_diff/association_discovery.rb +4 -4
  35. data/lib/paper_trail_diff/association_key.rb +10 -18
  36. data/lib/paper_trail_diff/association_traversal.rb +72 -92
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
  38. data/lib/paper_trail_diff/batch_preload.rb +2 -3
  39. data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
  40. data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
  41. data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
  42. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
  43. data/lib/paper_trail_diff/candidate_table.rb +160 -0
  44. data/lib/paper_trail_diff/change_attribution.rb +15 -23
  45. data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
  46. data/lib/paper_trail_diff/collection_transition.rb +3 -3
  47. data/lib/paper_trail_diff/comparison_batch.rb +13 -6
  48. data/lib/paper_trail_diff/database_time.rb +85 -0
  49. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
  50. data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
  51. data/lib/paper_trail_diff/diagnostics.rb +26 -86
  52. data/lib/paper_trail_diff/endpoint.rb +37 -5
  53. data/lib/paper_trail_diff/engine.rb +1 -1
  54. data/lib/paper_trail_diff/errors.rb +0 -6
  55. data/lib/paper_trail_diff/exact_column_type.rb +96 -0
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
  57. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  58. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
  59. data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
  60. data/lib/paper_trail_diff/nested_comparator.rb +42 -10
  61. data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +214 -182
  63. data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
  64. data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
  65. data/lib/paper_trail_diff/prepared_history.rb +27 -177
  66. data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
  67. data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
  68. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
  69. data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
  70. data/lib/paper_trail_diff/recorded_changes.rb +34 -10
  71. data/lib/paper_trail_diff/recorded_owner.rb +67 -0
  72. data/lib/paper_trail_diff/root_version_selection.rb +6 -2
  73. data/lib/paper_trail_diff/scope_condition.rb +120 -80
  74. data/lib/paper_trail_diff/scope_ranking.rb +14 -32
  75. data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
  76. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
  77. data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
  78. data/lib/paper_trail_diff/selection_window.rb +31 -0
  79. data/lib/paper_trail_diff/snapshot.rb +60 -58
  80. data/lib/paper_trail_diff/snapshot_members.rb +115 -0
  81. data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
  82. data/lib/paper_trail_diff/step.rb +1 -5
  83. data/lib/paper_trail_diff/stored_form.rb +146 -0
  84. data/lib/paper_trail_diff/stored_json_values.rb +8 -5
  85. data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
  86. data/lib/paper_trail_diff/stored_values.rb +35 -3
  87. data/lib/paper_trail_diff/support.rb +185 -35
  88. data/lib/paper_trail_diff/time_of_day.rb +13 -2
  89. data/lib/paper_trail_diff/time_range.rb +85 -11
  90. data/lib/paper_trail_diff/time_version_range.rb +5 -1
  91. data/lib/paper_trail_diff/timeline_builder.rb +5 -11
  92. data/lib/paper_trail_diff/timeline_range.rb +56 -19
  93. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
  94. data/lib/paper_trail_diff/total_order.rb +19 -5
  95. data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
  96. data/lib/paper_trail_diff/transaction_cut.rb +67 -327
  97. data/lib/paper_trail_diff/transaction_ends.rb +195 -0
  98. data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
  99. data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
  100. data/lib/paper_trail_diff/value_objects.rb +8 -6
  101. data/lib/paper_trail_diff/version.rb +1 -1
  102. data/lib/paper_trail_diff/version_association_candidate_scope.rb +12 -10
  103. data/lib/paper_trail_diff/version_boundary.rb +0 -29
  104. data/lib/paper_trail_diff/version_query.rb +49 -1
  105. data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
  106. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
  107. data/lib/paper_trail_diff/version_table.rb +8 -1
  108. data/lib/paper_trail_diff.rb +56 -110
  109. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
  110. data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
  111. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
  112. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
  113. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
  114. data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
  116. data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
  117. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
  120. data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
  122. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
  123. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
  124. data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
  125. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
  126. data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
  127. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
  128. data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
  129. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
  130. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
  131. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
  132. data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
  133. data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
  134. data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
  135. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
  136. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
  137. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
  138. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
  139. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
  140. data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
  141. data/sig/generated/paper_trail_diff/change_attribution.rbs +9 -16
  142. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
  143. data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
  144. data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
  145. data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
  148. data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
  149. data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
  150. data/sig/generated/paper_trail_diff/errors.rbs +0 -8
  151. data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
  152. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
  153. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
  154. data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
  155. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
  156. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +138 -94
  157. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
  158. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
  159. data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
  160. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
  161. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
  162. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
  163. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
  164. data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
  165. data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
  166. data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
  167. data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
  168. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
  169. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
  170. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
  171. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
  172. data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
  173. data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
  174. data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
  175. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
  176. data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
  177. data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
  178. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
  179. data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
  180. data/sig/generated/paper_trail_diff/support.rbs +96 -16
  181. data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
  182. data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
  183. data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
  184. data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
  185. data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
  186. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
  187. data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
  188. data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
  189. data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
  190. data/sig/generated/paper_trail_diff/transaction_ends.rbs +126 -0
  191. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
  192. data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
  193. data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
  194. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +11 -5
  195. data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
  196. data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
  197. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
  198. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
  199. data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
  200. data/sig/generated/paper_trail_diff.rbs +22 -23
  201. metadata +28 -20
  202. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
  203. data/lib/paper_trail_diff/fallback_paths.rb +0 -35
  204. data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
  205. data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
  206. data/lib/paper_trail_diff/historical_filter.rb +0 -210
  207. data/lib/paper_trail_diff/own_window.rb +0 -35
  208. data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
  209. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
  210. data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
  211. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
  212. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
  213. data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
  214. data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
  215. data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
@@ -4,15 +4,23 @@
4
4
  module PaperTrailDiff
5
5
  # Prepares the association history of a batch's roots, once per model class
6
6
  # across every version the batch replays, then analyzes each root from its
7
- # plan over its own window. AnalysisBatch and DeletedAnalysisBatch differ
8
- # only in how they find their roots and plans.
7
+ # plan over the batch's window. AnalysisBatch and DeletedAnalysisBatch
8
+ # differ only in how they find their roots and plans.
9
9
  class BatchedRootAnalyses
10
- # A root whose window moved to the start of a transaction crossing its
11
- # edge has its window in `windows`; the others take `time_range`.
12
- #: (time_range: TimeRange?, windows: Hash[Array[String], TimeRange], history_preparer: untyped, analyzer: untyped) -> void
13
- def initialize(time_range:, windows:, history_preparer:, analyzer:)
10
+ # `planner` selects the roots' plans over a window. On associations, a
11
+ # window's history is read from where the earliest transaction open at
12
+ # its start began. With `activity`, the roots are planned from there too,
13
+ # and each reports the transactions that end inside the window (see
14
+ # TransactionEnds). Without it each root version is reported where it
15
+ # was saved, so the roots are planned over the window as it is. `reach`
16
+ # answers where that transaction began, for a model and a window's start
17
+ # (see AssociationTraversal#reach_before).
18
+ #: (time_range: TimeRange?, planner: untyped, history_preparer: untyped, analyzer: untyped, activity: bool, reach: untyped) -> void
19
+ def initialize(time_range:, planner:, history_preparer:, analyzer:, activity:, reach:) # rubocop:disable Metrics/ParameterLists
14
20
  @time_range = time_range
15
- @windows = windows
21
+ @reach = reach
22
+ @activity = activity
23
+ @planner = planner
16
24
  @history_preparer = history_preparer
17
25
  @analyzer = analyzer
18
26
  end
@@ -20,50 +28,77 @@ module PaperTrailDiff
20
28
  # Preparation reads the roots' current association state as a fallback,
21
29
  # so a batch that has already loaded them passes them as `loaded`, rather
22
30
  # than have preparation walk that state one root at a time.
23
- #: (Array[untyped], Hash[Array[String], RootVersionPlan], ?loaded: Hash[Array[String], untyped]) -> Hash[Array[String], Analysis]
24
- def call(records, plans, loaded: {})
25
- records.group_by(&:class).each_value { |group| prepare(group, plans, loaded) }
31
+ #: (Array[untyped], ?loaded: Hash[Array[String], untyped]) -> Hash[Array[String], Analysis]
32
+ def call(records, loaded: {})
33
+ plans = {} #: Hash[Array[String], RootVersionPlan]
34
+ records.group_by(&:class).each_value { |group| plans.merge!(prepare(group, loaded)) }
26
35
  records.to_h do |record|
27
36
  key = Endpoint.identity(record)
28
- window = @windows.fetch(key, @time_range)
29
- [Support.immutable_copy(key), analysis(record, plans.fetch(key), window)]
37
+ [Support.immutable_copy(key), analysis(record, plans.fetch(key))]
30
38
  end
31
39
  end
32
40
 
33
41
  private
34
42
 
35
43
  # @rbs @time_range: TimeRange?
36
- # @rbs @windows: Hash[Array[String], TimeRange]
44
+ # @rbs @activity: bool
45
+ # @rbs @planner: untyped
37
46
  # @rbs @history_preparer: untyped
38
47
  # @rbs @analyzer: untyped
48
+ # @rbs @reach: untyped
49
+
50
+ # The plans the roots are read with: over the window, or with activity
51
+ # from where the earliest transaction open at its start began. The
52
+ # history is read from there either way.
53
+ #: (Array[untyped], Hash[Array[String], untyped]) -> Hash[Array[String], RootVersionPlan]
54
+ def prepare(records, loaded)
55
+ window = @time_range
56
+ range = window && widened(records.first.class, window)
57
+ plans = @planner.call(records, @activity ? range : window)
58
+ prepare_history(records, plans, loaded, range)
59
+ plans
60
+ end
61
+
62
+ #: (untyped, TimeRange) -> TimeRange
63
+ def widened(model, window)
64
+ reach = @reach.call(model, window.begin_time)
65
+ reach ? window.widened(reach) : window
66
+ end
39
67
 
40
68
  # Roots that close on their current state are prepared even without a
41
69
  # version in the window, since their descendants may have changed there.
42
- #: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
43
- def prepare(records, plans, loaded)
70
+ #: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped], TimeRange?) -> void
71
+ def prepare_history(records, plans, loaded, range)
44
72
  selected = records.map { |record| plans.fetch(Endpoint.identity(record)) }
45
73
  versions = selected.flat_map(&:reconstruction_versions)
46
74
  live = selected.any?(&:closing_record)
47
75
  return if versions.empty? && !live
48
76
 
49
- roots = records.map { |record| loaded.fetch(Endpoint.identity(record), record) }
50
- @history_preparer.call(roots, versions, **preparation_range(versions, live: live))
77
+ @history_preparer.call(current(records, loaded), versions,
78
+ **preparation_range(versions, range, live: live))
79
+ end
80
+
81
+ # Each root as the batch loaded it, where it did.
82
+ #: (Array[untyped], Hash[Array[String], untyped]) -> Array[untyped]
83
+ def current(records, loaded)
84
+ records.map { |record| loaded.fetch(Endpoint.identity(record), record) }
51
85
  end
52
86
 
53
87
  # A plan closing on the live record reads history up to now; the others
54
- # stop at the window's end or at the last version they replay past it, so
55
- # a past window does not load everything since.
56
- #: (Array[untyped], live: bool) -> Hash[Symbol, untyped]
57
- def preparation_range(versions, live:)
58
- ends = [versions.map(&:created_at).max, @time_range&.end_time, (Time.now.utc if live)]
59
- { start_at: TransactionCut.earliest_start(@time_range, @windows), end_at: ends.compact.max }
88
+ # stop at the window's end or where the transactions of the versions they
89
+ # replay past it end, so a past window does not load everything since.
90
+ #: (Array[untyped], TimeRange?, live: bool) -> Hash[Symbol, untyped]
91
+ def preparation_range(versions, range, live:)
92
+ ends = [TransactionCut.ends_at(versions), range&.end_time, (Time.now.utc if live)]
93
+ { start_at: range&.begin_time, end_at: ends.compact.max }
60
94
  end
61
95
 
62
96
  # A root with no versions in range has nothing to report, which is an
63
97
  # empty result rather than a failed request -- unless it closes on its
64
98
  # current state, where its descendants may still have moved.
65
- #: (untyped, RootVersionPlan, TimeRange?) -> Analysis
66
- def analysis(record, plan, window)
99
+ #: (untyped, RootVersionPlan) -> Analysis
100
+ def analysis(record, plan)
101
+ window = @time_range
67
102
  return @analyzer.empty.with_window(window) if plan.empty? && !plan.closing_record
68
103
 
69
104
  @analyzer.call(record, plan, window).with_window(window)
@@ -19,8 +19,8 @@ module PaperTrailDiff
19
19
  @view = view
20
20
  end
21
21
 
22
- # `window` is the root's window as the batch moved it to transaction edges,
23
- # or nil when the batch reads each root's whole history.
22
+ # `window` is the batch's window, or nil when it reads each root's whole
23
+ # history.
24
24
  #: (untyped, RootVersionPlan, TimeRange?) -> Analysis
25
25
  def call(record, plan, window)
26
26
  @preparer.call(record.class, historical: true)
@@ -28,9 +28,9 @@ module PaperTrailDiff
28
28
 
29
29
  TimelineBuilder.new(
30
30
  record,
31
- from: plan.versions.first,
32
- to: plan.final_endpoint,
33
- within: nil,
31
+ from: (plan.versions.first unless window),
32
+ to: (plan.final_endpoint unless window),
33
+ within: window,
34
34
  plan: plan,
35
35
  snapshotter: @timeline_snapshotter
36
36
  ).analyze
@@ -7,13 +7,11 @@ module PaperTrailDiff
7
7
  # every root are supported: a shared wall-clock window, or each root's own
8
8
  # whole history.
9
9
  class BatchedRootVersions
10
- #: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, whole: bool, windows: Hash[Array[String], TimeRange]) -> void
10
+ #: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, whole: bool) -> void
11
11
  def initialize( # rubocop:disable Metrics/ParameterLists
12
- records, time_range:, version_scope:, live_endpoints:, context_required:, whole:, windows:
12
+ records, time_range:, version_scope:, live_endpoints:, context_required:, whole:
13
13
  )
14
14
  @records = records
15
- # Roots whose window moved to a transaction's start, by identity.
16
- @windows = windows
17
15
  # An activity view needs a root to reconstruct from even in a window with
18
16
  # no root version, exactly as a single-record activity timeline does.
19
17
  @context_required = context_required
@@ -43,7 +41,6 @@ module PaperTrailDiff
43
41
  # @rbs @live_endpoints: Hash[Array[String], untyped]?
44
42
  # @rbs @context_required: bool
45
43
  # @rbs @whole: bool
46
- # @rbs @windows: Hash[Array[String], TimeRange]
47
44
 
48
45
  # Each statement reads the versions of 500 roots.
49
46
  #: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
@@ -52,44 +49,24 @@ module PaperTrailDiff
52
49
  in_range, chosen, trailing = model_versions(model_class, slice)
53
50
  slice.each do |record|
54
51
  key = Endpoint.identity(record)
55
- own = own_window(key, record.id.to_s, in_range, trailing)
56
- selected[key] = versions_for(*own, chosen, live_endpoint(key, record))
52
+ id = record.id.to_s
53
+ selected[key] = versions_for(in_range.fetch(id, []), trailing[id], chosen,
54
+ live_endpoint(key, record))
57
55
  end
58
56
  end
59
57
  end
60
58
 
61
- # Each root's own versions, and the first after its window (see OwnWindow).
62
- #: (Array[String], String, Hash[String, Array[untyped]], Hash[String, untyped]) -> [Array[untyped], untyped]
63
- def own_window(key, id, in_range, trailing)
64
- loaded = in_range.fetch(id, [])
65
- return [loaded, trailing[id]] if @windows.empty?
66
-
67
- # A batch moves windows only when it has one, so this is never nil.
68
- window = @windows.fetch(key) { @time_range } #: untyped
69
- own, past = OwnWindow.split(window, loaded)
70
- [own, past || trailing[id]]
71
- end
72
-
73
59
  #: (untyped, Array[untyped]) -> [Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped]]
74
60
  def model_versions(model_class, records)
75
61
  range = @time_range
76
62
  empty = {} #: Hash[String, untyped]
77
- widest = widest_range(records)
78
63
  [
79
- grouped_versions(model_class, records, widest),
80
- chosen_version_ids(model_class, records, widest),
64
+ grouped_versions(model_class, records, range),
65
+ chosen_version_ids(model_class, records, range),
81
66
  range ? trailing_versions(model_class, records, range) : empty
82
67
  ]
83
68
  end
84
69
 
85
- #: (Array[untyped]) -> TimeRange?
86
- def widest_range(records)
87
- range = @time_range
88
- return unless range
89
-
90
- OwnWindow.widest(range, records.filter_map { |record| @windows[Endpoint.identity(record)] })
91
- end
92
-
93
70
  #: (Array[untyped], untyped, Set[untyped]?, untyped) -> RootVersionPlan
94
71
  def versions_for(in_range, after_range, chosen, live_endpoint)
95
72
  RootVersionSelection.new(
@@ -4,7 +4,7 @@
4
4
  module PaperTrailDiff
5
5
  # Reconstructs selected root branches and merges them into a prior immutable snapshot.
6
6
  class BranchSnapshotRefresher
7
- #: (ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped, ?prepared_record_after: untyped, ?root_state: untyped) -> void
7
+ #: (ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, member_snapshot: untyped, record_transition: untyped, ?prepared_record_after: untyped, ?root_state: untyped) -> void
8
8
  def initialize( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
9
9
  ignore_policy:,
10
10
  traversal:,
@@ -12,7 +12,7 @@ module PaperTrailDiff
12
12
  normalizer:,
13
13
  full_snapshotter:,
14
14
  partial_snapshotter:,
15
- association_reader:,
15
+ member_snapshot:,
16
16
  record_transition:,
17
17
  prepared_record_after: nil,
18
18
  root_state: nil
@@ -27,7 +27,7 @@ module PaperTrailDiff
27
27
  @event_refresher = ActivityEventSnapshotRefresher.new(
28
28
  traversal: traversal, pool: pool,
29
29
  components: method(:components),
30
- association_reader: association_reader,
30
+ member_snapshot: member_snapshot,
31
31
  record_transition: record_transition,
32
32
  prepared_record_after: prepared_record_after
33
33
  )
@@ -39,6 +39,7 @@ module PaperTrailDiff
39
39
  record_transition: record_transition,
40
40
  root_state: root_state
41
41
  )
42
+ @applier = ActivityTransactionApplier.new(@event_refresher, @root_refresher)
42
43
  end
43
44
 
44
45
  # Without associations there is no prepared history, so nothing but the
@@ -71,7 +72,6 @@ module PaperTrailDiff
71
72
  )
72
73
  return full_snapshot(root_endpoint, context_endpoint) unless previous_snapshot
73
74
 
74
- branches = with_habtm(root_endpoint, context_endpoint, branches)
75
75
  if isolated && event && branches.length > 1
76
76
  return refresh_independent_branches(root_endpoint, context_endpoint, previous_snapshot,
77
77
  branches, event)
@@ -85,6 +85,20 @@ module PaperTrailDiff
85
85
  refreshed(root_endpoint, context_endpoint, previous_snapshot, branches)
86
86
  end
87
87
 
88
+ # The snapshot after a transaction that saved several records: each of
89
+ # its events applied in turn to the record it saved, as an event alone in
90
+ # its transaction is. Where one cannot be applied that way, the
91
+ # transaction's branches are read again instead, or the whole snapshot
92
+ # when the root is among the records it saved (`branches` is nil).
93
+ #: (untyped, untyped, RecordSnapshot, Array[String]?, Array[ActivityEvent]) -> RecordSnapshot?
94
+ def apply_transaction(root_endpoint, context_endpoint, previous_snapshot, branches, events)
95
+ snapshot = @applier.call(root_endpoint, context_endpoint, previous_snapshot, events)
96
+ return snapshot if snapshot
97
+ return full_snapshot(root_endpoint, context_endpoint) unless branches
98
+
99
+ refreshed(root_endpoint, context_endpoint, previous_snapshot, branches)
100
+ end
101
+
88
102
  private
89
103
 
90
104
  # @rbs @tree: AssociationTree
@@ -96,16 +110,7 @@ module PaperTrailDiff
96
110
  # @rbs @components: Hash[Array[String], [AssociationTree, SnapshotNormalizer]]
97
111
  # @rbs @event_refresher: ActivityEventSnapshotRefresher
98
112
  # @rbs @root_refresher: ActivityRootSnapshotRefresher
99
-
100
- # A root version's HABTM members include any created earlier in its
101
- # transaction. A range ending at that version leaves those creations out
102
- # as events, so the branch is read again there, whatever event led to it.
103
- #: (untyped, untyped, Array[String]) -> Array[String]
104
- def with_habtm(root_endpoint, context_endpoint, branches)
105
- root = Endpoint.version?(root_endpoint) &&
106
- VersionBoundary.same_version?(root_endpoint, context_endpoint)
107
- root ? branches | @traversal.habtm_paths(RecordedClass.for(root_endpoint)) : branches
108
- end
113
+ # @rbs @applier: ActivityTransactionApplier
109
114
 
110
115
  #: (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent) -> RecordSnapshot?
111
116
  def refresh_independent_branches( # rubocop:disable Metrics/MethodLength
@@ -0,0 +1,160 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ require 'securerandom'
5
+
6
+ module PaperTrailDiff
7
+ # Holds a selection's candidate ids where every page of the selection can
8
+ # join them, so that no page lists them.
9
+ #
10
+ # Each page of a plucked selection repeats its candidates, and SQL Server
11
+ # compiles a statement with its values written in afresh: with 10,000 ids a
12
+ # page took about 0.7 s, and with 20,000 a page could outlast the adapter's
13
+ # default timeout. On SQL Server, a long list is written once into a
14
+ # temporary table, and each page selects from it instead. Other databases
15
+ # take the list as before: they parse it quickly, and the table would cost
16
+ # them statements of their own.
17
+ #
18
+ # Active Record counts the table's statements as writes, so a read that
19
+ # prevents writes, as a replica read through Rails' automatic role switching
20
+ # does, takes the list instead.
21
+ #
22
+ # A temporary table belongs to the connection that made it, so the block runs
23
+ # on one connection, and the table is dropped when it returns or raises,
24
+ # even when filling it is what failed. A
25
+ # reconnect inside the block, as Active Record makes to retry a read after
26
+ # losing the connection, loses the table, and the read then fails naming it.
27
+ module CandidateTable
28
+ # More ids than this go to a table: one statement's worth, as the gem
29
+ # lists elsewhere, compiles quickly.
30
+ THRESHOLD = Support::IDS_PER_STATEMENT #: Integer
31
+
32
+ # SQL Server inserts at most 1,000 rows in one VALUES list.
33
+ ROWS_PER_INSERT = 1_000
34
+
35
+ # Yields the ids as they were given, or, on SQL Server with more than
36
+ # THRESHOLD of them, a relation that selects them from a table, which a
37
+ # condition such as `where(id: ...)` reads as a subquery.
38
+ #: [T] (untyped, Array[String]) { (untyped) -> T } -> T
39
+ def self.with(model, ids)
40
+ return yield(ids) unless ids.length > THRESHOLD
41
+
42
+ Support.with_connection(model) do |connection|
43
+ next yield(ids) unless table?(connection)
44
+
45
+ temporary(connection, model) do |name|
46
+ insert_values(connection, model, name, ids)
47
+ yield selection(model, name)
48
+ end
49
+ end
50
+ end
51
+
52
+ # Yields the subqueries as they were given, or, on SQL Server, one
53
+ # relation that selects their ids from a table each fills in turn.
54
+ #
55
+ # A page that matches its rows against several subqueries joined by OR
56
+ # has SQL Server plan them as one statement: with 1,600 orders and the
57
+ # subqueries for their line items, it ran a line items' subquery again
58
+ # for each order and took about 38 s, though each subquery alone took
59
+ # under 0.2 s. Filled one statement at a time, each subquery runs once,
60
+ # and every page then reads one keyed table. The ids stay in the
61
+ # database, so a busy window costs no list in Ruby.
62
+ #: [T] (untyped, Array[untyped]) { (Array[untyped]) -> T } -> T
63
+ def self.union(model, relations)
64
+ return yield(relations) unless relations.length > 1
65
+
66
+ Support.with_connection(model) do |connection|
67
+ next yield(relations) unless table?(connection)
68
+
69
+ temporary(connection, model) do |name|
70
+ relations.each { |relation| insert_selected(connection, name, relation) }
71
+ yield [selection(model, name)]
72
+ end
73
+ end
74
+ end
75
+
76
+ #: (untyped) -> bool
77
+ def self.table?(connection)
78
+ connection.adapter_name == 'SQLServer' && !connection.preventing_writes?
79
+ end
80
+
81
+ # The table is dropped even when making or filling it is what failed.
82
+ #: [T] (untyped, untyped) { (String) -> T } -> T
83
+ def self.temporary(connection, model)
84
+ name = "#paper_trail_diff_candidates_#{SecureRandom.hex(8)}"
85
+ begin
86
+ create(connection, model, name)
87
+ yield name
88
+ ensure
89
+ drop(connection, name)
90
+ end
91
+ end
92
+
93
+ # A condition such as `where(id: ...)` reads this as a subquery.
94
+ #: (untyped, String) -> untyped
95
+ def self.selection(model, name)
96
+ model.unscoped.from("#{name} AS candidates").select('candidates.id')
97
+ end
98
+
99
+ # The column takes the key's type and collation, so that comparing the two
100
+ # neither converts every row nor meets tempdb's collation.
101
+ #: (untyped, untyped, String) -> void
102
+ def self.create(connection, model, name)
103
+ column = model.columns_hash.fetch(model.primary_key)
104
+ connection.execute("CREATE TABLE #{name} (id #{column_type(column)} PRIMARY KEY)")
105
+ end
106
+
107
+ #: (untyped, untyped, String, Array[String]) -> void
108
+ def self.insert_values(connection, model, name, ids)
109
+ type = model.type_for_attribute(model.primary_key)
110
+ ids.uniq.each_slice(ROWS_PER_INSERT) do |slice|
111
+ values = slice.map { |id| "(#{connection.quote(type.serialize(type.cast(id)))})" }
112
+ insert(connection, name, "SELECT id FROM (VALUES #{values.join(', ')}) AS listed (id)")
113
+ end
114
+ end
115
+
116
+ #: (untyped, String, untyped) -> void
117
+ def self.insert_selected(connection, name, relation)
118
+ insert(connection, name, relation.to_sql)
119
+ end
120
+
121
+ # The source selects one column. An id already in the table, or none, is
122
+ # left out, so the key holds each once.
123
+ #
124
+ # The statement starts with WITH rather than INSERT. The adapter reads the
125
+ # table of every statement that starts with INSERT from the catalog, to
126
+ # learn whether it has an identity column. For a temporary table that is a
127
+ # query on tempdb's catalog, which another report's DROP TABLE can hold
128
+ # locks on: two reports at the same time deadlocked there, and SQL Server
129
+ # killed one of them.
130
+ #: (untyped, String, String) -> void
131
+ def self.insert(connection, name, source)
132
+ connection.execute("WITH selected (id) AS (#{source}) " \
133
+ "INSERT INTO #{name} (id) SELECT id FROM selected " \
134
+ "WHERE id IS NOT NULL EXCEPT SELECT id FROM #{name}")
135
+ end
136
+
137
+ # The table can be gone already: a timeout that cost the connection,
138
+ # which Active Record then reconnected, takes it along. A failed drop is
139
+ # not raised, so that the error that ended the block is the one the caller
140
+ # sees; a table left behind goes when its connection closes.
141
+ #: (untyped, String) -> void
142
+ def self.drop(connection, name)
143
+ connection.execute("IF OBJECT_ID('tempdb..#{name}') IS NOT NULL DROP TABLE #{name}")
144
+ rescue StandardError
145
+ nil
146
+ end
147
+
148
+ # The adapter writes an integer type with its size in bytes, as
149
+ # `bigint(8)`, which SQL Server does not accept back.
150
+ #: (untyped) -> String
151
+ def self.column_type(column)
152
+ type = column.sql_type.sub(/\A(tinyint|smallint|int|bigint)\(\d+\)\z/, '\\1')
153
+ collation = column.collation if column.respond_to?(:collation)
154
+ collation ? "#{type} COLLATE #{collation}" : type
155
+ end
156
+
157
+ private_class_method :table?, :temporary, :selection, :create, :insert_values, :insert_selected,
158
+ :insert, :drop, :column_type
159
+ end
160
+ end
@@ -12,9 +12,10 @@ module PaperTrailDiff
12
12
  # recorded of it: each run of recorded changes is credited to the version
13
13
  # that ended it, or the whole change to the last of the record's versions
14
14
  # when what they recorded was not read. A record that appeared or
15
- # disappeared is credited to its own create or destroy. Any other row keeps
16
- # the step's source: a record that joined a collection or became a to-one
17
- # target through another record's change, for one.
15
+ # disappeared is credited to its own create or destroy, or else to the
16
+ # last of its versions there, as a record that moved by its own update.
17
+ # Any other row keeps the step's source: a record that joined a collection
18
+ # or became a to-one target through another record's change, for one.
18
19
  #
19
20
  # With recorded changes read, the part of a field's change that those
20
21
  # versions did not record is split off and credited to an unversioned
@@ -26,9 +27,7 @@ module PaperTrailDiff
26
27
  # - a version that recorded nothing, such as a `touch`, or a table without
27
28
  # `object_changes`;
28
29
  # - a column PaperTrail is told not to record (see RecordedColumns);
29
- # - a field a create left out, which held its default when created;
30
- # - the start of a transaction that began before the history's start (see
31
- # PreparedHistoryLoader#reload), whose earlier versions were not read.
30
+ # - a field a create left out, which held its default when created.
32
31
  class ChangeAttribution
33
32
  # A transaction's boundaries, in the order the history kept them. Every
34
33
  # step the transaction opens shares the one list and reads the boundaries
@@ -81,14 +80,11 @@ module PaperTrailDiff
81
80
 
82
81
  # `root` is the record the timeline is about, which rows name by leaving
83
82
  # `record` nil. `transaction` holds the boundaries of the step's
84
- # transaction, of which the first `preceding` came before its sources;
85
- # `complete` says whether the history holds every version that
86
- # transaction saved before them.
87
- #: (root: RecordReference, sources: Array[ActivityBoundary], complete: bool, transaction: Transaction, ?preceding: Integer) -> void
88
- def initialize(root:, sources:, complete:, transaction:, preceding: transaction.length)
83
+ # transaction, of which the first `preceding` came before its sources.
84
+ #: (root: RecordReference, sources: Array[ActivityBoundary], transaction: Transaction, ?preceding: Integer) -> void
85
+ def initialize(root:, sources:, transaction:, preceding: transaction.length)
89
86
  @root = root
90
87
  @sources = Transaction.new(sources)
91
- @complete = complete
92
88
  @transaction = transaction
93
89
  @preceding = preceding
94
90
  @versions = {} #: Hash[Array[String], Array[ActivityBoundary]]
@@ -98,8 +94,8 @@ module PaperTrailDiff
98
94
  # The same transaction, read through a transaction group's sources.
99
95
  #: (Array[ActivityBoundary]) -> ChangeAttribution
100
96
  def with_sources(sources)
101
- self.class.new(root: @root, sources: sources, complete: @complete,
102
- transaction: @transaction, preceding: @preceding)
97
+ self.class.new(root: @root, sources: sources, transaction: @transaction,
98
+ preceding: @preceding)
103
99
  end
104
100
 
105
101
  # The row as the rows it splits into, each credited to its change's
@@ -120,7 +116,6 @@ module PaperTrailDiff
120
116
 
121
117
  # @rbs @root: RecordReference
122
118
  # @rbs @sources: Transaction
123
- # @rbs @complete: bool
124
119
  # @rbs @transaction: Transaction
125
120
  # @rbs @preceding: Integer
126
121
  # @rbs @versions: Hash[Array[String], Array[ActivityBoundary]]
@@ -128,9 +123,7 @@ module PaperTrailDiff
128
123
  # A field's change follows what the record's versions recorded of it,
129
124
  # from the value the row starts at (see #relevant): each run of recorded
130
125
  # changes is one row, credited to the version that ended it, and a value
131
- # that moved where they do not meet was saved without a version. Where
132
- # the row's start leads to no version, the move to the first of them is
133
- # told apart only when the history holds the whole transaction.
126
+ # that moved where they do not meet was saved without a version.
134
127
  #: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
135
128
  def changed(row, versions)
136
129
  touched = recorded_changes(versions, row.attribute)
@@ -139,8 +132,7 @@ module PaperTrailDiff
139
132
  relevant = relevant(touched, row)
140
133
  return unrecorded(row, versions) if relevant.empty?
141
134
 
142
- trusted = @complete || relevant.length < touched.length
143
- rows_for(row, chain(row.from, row.to, relevant, trusted), :changed)
135
+ rows_for(row, chain(row.from, row.to, relevant, true), :changed)
144
136
  end
145
137
 
146
138
  # The changes that make up the row's: from the last one that left the
@@ -168,7 +160,7 @@ module PaperTrailDiff
168
160
  # record every change of it they make.
169
161
  #: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
170
162
  def unrecorded(row, versions)
171
- return [credit(row, versions.last)] unless @complete && recorded_column?(row)
163
+ return [credit(row, versions.last)] unless recorded_column?(row)
172
164
 
173
165
  [credit(row, unversioned(row))]
174
166
  end
@@ -180,7 +172,7 @@ module PaperTrailDiff
180
172
  #: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
181
173
  def added(row, versions)
182
174
  index = versions.index { |version| version.event == 'create' }
183
- return [row] unless index
175
+ return [credit(row, versions.last)] unless index
184
176
 
185
177
  created = versions.drop(index)
186
178
  touched = recorded_changes(created, row.attribute)
@@ -246,7 +238,7 @@ module PaperTrailDiff
246
238
  #: (ChangeRow, Array[ActivityBoundary]) -> ChangeRow
247
239
  def removed(row, versions)
248
240
  destroy = versions.find { |version| version.event == 'destroy' }
249
- destroy ? credit(row, destroy) : row
241
+ credit(row, destroy || versions.last)
250
242
  end
251
243
 
252
244
  # The changes the versions recorded of a field, each with its version: