paper_trail_diff 0.17.1 → 0.18.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.
Files changed (215) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +648 -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 +194 -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 +124 -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
@@ -10,16 +10,24 @@ module PaperTrailDiff
10
10
  LAST_REMOVED = '`:last` was removed because it left out the latest change: omit `to:` ' \
11
11
  'to end at current state, or pass a version'
12
12
 
13
+ # The one symbol a boundary can be, for a timeline's range and for
14
+ # compare_many's endpoints alike.
15
+ #: (Symbol) -> void
16
+ def self.check_symbol!(boundary)
17
+ raise InvalidTimelineRangeError, LAST_REMOVED if boundary == :last
18
+ return if BOUNDARY_SYMBOLS.include?(boundary)
19
+
20
+ raise InvalidTimelineRangeError,
21
+ "unsupported boundary: #{boundary.inspect}; use :first, a version, or a record"
22
+ end
23
+
13
24
  attr_reader :from #: untyped
14
25
  attr_reader :to #: untyped
15
26
  attr_reader :time_range #: TimeRange?
16
27
 
17
- # `traversal` names the requested paths, which decide where a window's
18
- # edges move (see TransactionCut).
19
- #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
20
- def initialize(record, from:, to:, within:, version_scope: nil, plan: nil, live_endpoint: nil, traversal: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
28
+ #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
29
+ def initialize(record, from:, to:, within:, version_scope: nil, plan: nil, live_endpoint: nil) # rubocop:disable Metrics/ParameterLists
21
30
  @record = record
22
- @traversal = traversal
23
31
  @plan = plan
24
32
  @live_endpoint = live_endpoint
25
33
  @version_scope = version_scope
@@ -45,6 +53,9 @@ module PaperTrailDiff
45
53
  # The plan says which pairs of versions become steps, which a filter can
46
54
  # make different from adjacent pairs of the selected versions. A `whole`
47
55
  # plan replays every version in the range; see RootVersionSelection.
56
+ #: () -> bool
57
+ def preselected? = !@plan.nil?
58
+
48
59
  #: (?context_required: bool, ?whole: bool) -> RootVersionPlan
49
60
  def select_plan(context_required: false, whole: false)
50
61
  preselected = @plan
@@ -60,6 +71,33 @@ module PaperTrailDiff
60
71
  explicit_plan(whole)
61
72
  end
62
73
 
74
+ # The plan over the window widened to start at its `reach`: where the
75
+ # earliest transaction across its start began (see PreparedHistoryLoader).
76
+ #: (untyped, context_required: bool) -> RootVersionPlan
77
+ def reach_plan(reach, context_required:)
78
+ range = time_range #: TimeRange
79
+ TimeVersionRange.new(
80
+ @record, time_range: range.widened(reach), version_scope: @version_scope,
81
+ live_endpoint: @live_endpoint
82
+ ).select_plan(context_required: context_required, whole: true)
83
+ end
84
+
85
+ # The plan of what the window reports, from the root versions a `wide`
86
+ # plan replays: those whose transactions end inside the window, bounded
87
+ # by the first that ends after it (see TransactionEnds). The root's own
88
+ # mutations among them are those the wide plan names, which a filter
89
+ # chose.
90
+ #: (RootVersionPlan, TransactionEnds, context_required: bool) -> RootVersionPlan
91
+ def reporting_plan(wide, ends, context_required:)
92
+ inside, after = placed(wide.reconstruction_versions, ends)
93
+ RootVersionSelection.new(
94
+ in_range: inside, selected: inside.select { |version| wide.mutation?(version) },
95
+ after_range: after, windowed: true,
96
+ context_required: context_required,
97
+ live_endpoint: wide.closing_record
98
+ ).call
99
+ end
100
+
63
101
  #: () -> bool
64
102
  def time?
65
103
  !time_range.nil?
@@ -79,7 +117,6 @@ module PaperTrailDiff
79
117
  private
80
118
 
81
119
  # @rbs @record: untyped
82
- # @rbs @traversal: AssociationTraversal?
83
120
  # @rbs @plan: RootVersionPlan?
84
121
  # @rbs @version_scope: untyped
85
122
  # @rbs @live_endpoint: untyped
@@ -88,6 +125,16 @@ module PaperTrailDiff
88
125
  # @rbs @from: untyped
89
126
  # @rbs @to: untyped
90
127
 
128
+ # The versions whose transactions end inside the window, and the first
129
+ # whose transaction ends after it.
130
+ #: (Array[untyped], TransactionEnds) -> [Array[untyped], untyped]
131
+ def placed(versions, ends)
132
+ range = time_range #: TimeRange
133
+ started = versions.reject { |version| ends.last(version).created_at < begin_time }
134
+ inside, after = started.partition { |version| range.include?(ends.last(version).created_at) }
135
+ [inside, after.first]
136
+ end
137
+
91
138
  #: (bool) -> RootVersionPlan
92
139
  def explicit_plan(whole)
93
140
  return RootVersionPlan.empty if unresolved?
@@ -112,13 +159,8 @@ module PaperTrailDiff
112
159
  #: (untyped) -> untyped
113
160
  def resolve(boundary)
114
161
  return boundary unless symbolic?(boundary)
115
- raise InvalidTimelineRangeError, LAST_REMOVED if boundary == :last
116
-
117
- unless BOUNDARY_SYMBOLS.include?(boundary)
118
- raise InvalidTimelineRangeError,
119
- "unsupported boundary: #{boundary.inspect}; use :first, a version, or a record"
120
- end
121
162
 
163
+ self.class.check_symbol!(boundary)
122
164
  ordered_versions.first
123
165
  end
124
166
 
@@ -127,18 +169,13 @@ module PaperTrailDiff
127
169
  VersionQuery.chronological(Endpoint.versions(@record))
128
170
  end
129
171
 
130
- # A batch passes each root the window it already moved to transaction
131
- # edges; a single record's window is moved here.
172
+ # A batch passes each root its window as it read it.
132
173
  #: (untyped) -> TimeRange?
133
174
  def build_time_range(within)
134
175
  return if within.nil?
135
176
  return within if within.instance_of?(TimeRange)
136
177
 
137
- range = TimeRange.new(within)
138
- return range unless Support.versioned?(@record.class)
139
-
140
- TransactionCut.windows(@record.class, [@record], range, traversal: @traversal)
141
- .fetch(@record.id.to_s, range)
178
+ TimeRange.for(within, [@record.class])
142
179
  end
143
180
 
144
181
  #: () -> void
@@ -10,10 +10,19 @@ module PaperTrailDiff
10
10
  @live_snapshotter = live_snapshotter
11
11
  end
12
12
 
13
- #: (untyped, Array[untyped]) -> PreparedTimelineSnapshots
14
- def prepare(record, versions)
15
- history = @store.prepare(record, versions)
16
- PreparedTimelineSnapshots.new(history, store: @store, live_snapshotter: @live_snapshotter)
13
+ # Each root version is reported where it was saved, and the records
14
+ # around it read as they stood before every transaction that had not
15
+ # ended yet (see TransactionEnds). So a window's history is read from
16
+ # where the earliest transaction open at its start began, as a batch
17
+ # reads it: one of them may have saved a record before the window. A
18
+ # whole history begins at the root's first version instead.
19
+ #: (untyped, Array[untyped], ?start_at: untyped) -> PreparedTimelineSnapshots
20
+ def prepare(record, versions, start_at: nil)
21
+ start_at = @store.reach_before(record, start_at) || start_at
22
+ history = @store.prepare(record, versions, start_at: start_at)
23
+ ends = history&.transaction_ends(versions)
24
+ PreparedTimelineSnapshots.new(history, ends, store: @store,
25
+ live_snapshotter: @live_snapshotter)
17
26
  end
18
27
 
19
28
  # @rbs @store: HistoricalSnapshotStore
@@ -25,9 +34,10 @@ module PaperTrailDiff
25
34
  # nil create state, is kept for this root only and released with it, and
26
35
  # batch memory does not retain every reconstructed graph.
27
36
  class PreparedTimelineSnapshots
28
- #: (PreparedHistory?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
29
- def initialize(history, store:, live_snapshotter:)
37
+ #: (PreparedHistory?, TransactionEnds?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
38
+ def initialize(history, ends, store:, live_snapshotter:)
30
39
  @history = history
40
+ @ends = ends
31
41
  @store = store
32
42
  @live_snapshotter = live_snapshotter
33
43
  @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
@@ -43,11 +53,25 @@ module PaperTrailDiff
43
53
  @snapshots[key] = if Endpoint.record?(endpoint)
44
54
  @live_snapshotter.call(endpoint)
45
55
  else
46
- @store.uncached(endpoint, endpoint, history: @history)
56
+ at_version(endpoint)
47
57
  end
48
58
  end
49
59
 
60
+ private
61
+
62
+ #: (untyped) -> RecordSnapshot?
63
+ def at_version(version)
64
+ history = @history
65
+ ends = @ends
66
+ return @store.uncached(version, version) unless history && ends
67
+
68
+ snapshot = nil #: RecordSnapshot?
69
+ history.reading(ends) { snapshot = @store.uncached(version, version, history: history) }
70
+ snapshot
71
+ end
72
+
50
73
  # @rbs @history: PreparedHistory?
74
+ # @rbs @ends: TransactionEnds?
51
75
  # @rbs @store: HistoricalSnapshotStore
52
76
  # @rbs @live_snapshotter: untyped
53
77
  # @rbs @snapshots: Hash[Array[untyped], RecordSnapshot?]
@@ -11,13 +11,21 @@ module PaperTrailDiff
11
11
  # already sorts by the key. Such an order is kept as given, since SQL
12
12
  # Server rejects a column listed twice. So is the order of a relation
13
13
  # grouped by anything but the key: each of its rows is a group, which a
14
- # database sorts only by what it groups or aggregates. A relation answers
15
- # for its model the key and table name read here.
14
+ # database sorts only by what it groups or aggregates; one without an order
15
+ # is refused. A relation answers for its model the key and table name read
16
+ # here.
16
17
  #: (untyped) -> untyped
17
18
  def self.apply(relation)
18
19
  orders = relation.order_values
19
20
  return relation if orders.any? { |order| key?(order, relation) }
20
- return relation if !orders.empty? && grouped_by_other?(relation)
21
+
22
+ if grouped_by_other?(relation)
23
+ return relation unless orders.empty?
24
+
25
+ # Sorting its groups by the key is what the database would reject.
26
+ raise ConfigurationError, 'scope: a relation grouped by anything but its primary key ' \
27
+ 'needs an order of its own to be read in pages'
28
+ end
21
29
 
22
30
  relation.order(relation.primary_key => :asc)
23
31
  end
@@ -40,12 +48,18 @@ module PaperTrailDiff
40
48
  end
41
49
  private_class_method :key?
42
50
 
51
+ # A name alone or after a table's, each as it is or in the quotes of any
52
+ # adapter here: "name", `name` or [name].
53
+ QUALIFIED_NAME = /(?:["`\[]?(\w+)["`\]]?\.)?["`\[]?(\w+)["`\]]?/
54
+ private_constant :QUALIFIED_NAME
55
+
43
56
  # Whether SQL text names the key, alone or after its table's name. That
44
57
  # also finds a key the text only uses, as in `LENGTH(id)`, which then goes
45
- # without the tie-breaker, but it misses no sort by the key.
58
+ # without the tie-breaker, but it misses no sort by the key. Another
59
+ # table's key, quoted or not, is not this one.
46
60
  #: (String, untyped) -> bool
47
61
  def self.key_in_sql?(sql, relation)
48
- names = sql.scan(/(?:(\w+)\.)?(\w+)/) #: Array[[String?, String]]
62
+ names = sql.scan(QUALIFIED_NAME) #: Array[[String?, String]]
49
63
  names.any? do |table, column|
50
64
  column.casecmp?(relation.primary_key) && (table.nil? || table.casecmp?(relation.table_name))
51
65
  end
@@ -0,0 +1,138 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Tells apart transactions that share a number.
6
+ #
7
+ # PaperTrail numbers a transaction by the id of the first version it saved,
8
+ # in whichever version table that was, and writes the number on every
9
+ # version the transaction saves, in any table. Two tables count their ids
10
+ # apart, so a transaction that began in one can take the number of another
11
+ # that began elsewhere, and a table then holds versions of both under one
12
+ # number. Read by number alone, a window that starts inside the later one
13
+ # is read from where the earlier one began, which can be years before.
14
+ #
15
+ # The version a transaction saved first carries its own id as its number:
16
+ # its anchor, saved when the transaction began. Two versions of one number
17
+ # on either side of an instant belong to one transaction only when no
18
+ # anchor of that number lies between either of them and the instant.
19
+ #
20
+ # Only the version classes loaded when a history is read are known, so one
21
+ # that nothing has loaded yet is not consulted, nor is one in another
22
+ # database, whose table a statement here cannot read. An anchor that was
23
+ # pruned separates nothing, and two transactions of one number that ran at
24
+ # the same time are not told apart.
25
+ module TransactionAnchors
26
+ # A condition on versions of `table` that keeps those no anchor separates
27
+ # from the start. Nothing when the model's version table is the only one,
28
+ # where a number names one transaction.
29
+ #: (untyped, Time, ?untyped) -> untyped
30
+ def self.unbroken(version_class, start, table = version_class.arel_table)
31
+ classes = version_classes(version_class)
32
+ return if classes.length < 2
33
+
34
+ classes.each_with_index.map do |anchors, index|
35
+ none(anchors, index, start, table)
36
+ end.reduce(:and)
37
+ end
38
+
39
+ # `relation` narrowed to the versions no anchor separates from the start.
40
+ #: (untyped, untyped, Time) -> untyped
41
+ def self.scope(relation, version_class, start)
42
+ condition = unbroken(version_class, start)
43
+ condition ? relation.where(condition) : relation
44
+ end
45
+
46
+ # `relation` narrowed to the versions of the transactions that these
47
+ # versions (or the versions of these ids), saved after the start, belong
48
+ # to: of a number's versions before the start, those of the transaction
49
+ # that went on to save one of these.
50
+ #: (untyped, untyped, Time, Array[untyped]) -> untyped
51
+ def self.continued(relation, version_class, start, versions)
52
+ condition = unbroken(version_class, start)
53
+ return relation unless condition
54
+
55
+ later = version_class.where(version_class.primary_key => versions).where(condition)
56
+ relation.where(condition).where(transaction_id: later.select(:transaction_id))
57
+ end
58
+
59
+ # Those of the numbers that more than one transaction took: each the id
60
+ # of the first version of a transaction in more than one version table.
61
+ # None when the model's version table is the only one.
62
+ #: (untyped, Array[untyped]) -> Array[untyped]
63
+ def self.shared(version_class, numbers)
64
+ classes = version_classes(version_class)
65
+ return [] if classes.length < 2
66
+
67
+ firsts = classes.flat_map { |anchors| first_ids(anchors, numbers) }
68
+ firsts.tally.select { |_number, count| count > 1 }.keys
69
+ end
70
+
71
+ # The ids among these of the versions that began a transaction.
72
+ #: (untyped, Array[untyped]) -> Array[untyped]
73
+ def self.first_ids(anchors, numbers)
74
+ key = anchors.primary_key
75
+ table = anchors.arel_table
76
+ anchors.where(key => numbers).where(table[key].eq(table[:transaction_id])).pluck(key)
77
+ end
78
+ private_class_method :first_ids
79
+
80
+ # The version classes whose ids can number a transaction of this one's
81
+ # versions, one for each table, in the order of their tables' names.
82
+ #: (untyped) -> Array[untyped]
83
+ def self.version_classes(version_class)
84
+ type = version_class.type_for_attribute('transaction_id').type
85
+ Support.constant('ActiveRecord::Base').descendants
86
+ .select { |candidate| numbers?(candidate, version_class, type) }
87
+ .uniq(&:table_name).sort_by(&:table_name)
88
+ end
89
+ private_class_method :version_classes
90
+
91
+ # Whether the candidate's ids number transactions the version class can
92
+ # read here: a version table in the same database, with ids of the type
93
+ # the number is kept as.
94
+ #: (untyped, untyped, untyped) -> bool
95
+ def self.numbers?(candidate, version_class, type)
96
+ candidate.include?(Support.constant('PaperTrail::VersionConcern')) &&
97
+ !candidate.abstract_class? &&
98
+ candidate.connection_db_config == version_class.connection_db_config &&
99
+ candidate.table_exists? &&
100
+ candidate.column_names.include?('transaction_id') &&
101
+ candidate.primary_key.is_a?(String) &&
102
+ candidate.type_for_attribute(candidate.primary_key).type == type
103
+ end
104
+ private_class_method :numbers?
105
+
106
+ # No anchor of the version's number between the version and the start:
107
+ # none after a version saved before the start and before the start, and
108
+ # none after the start and up to a version saved after it, which the
109
+ # version's own anchor is when its transaction began there.
110
+ #: (untyped, Integer, Time, untyped) -> untyped
111
+ def self.none(anchors, index, start, table)
112
+ anchor = anchors.arel_table.alias("paper_trail_diff_anchors_#{index}")
113
+ separating = numbering(anchor, anchors.primary_key, table)
114
+ .and(between(anchor[:created_at], table[:created_at], start))
115
+ Support.arel::SelectManager.new(anchor).project(Support.arel.sql('1'))
116
+ .where(separating).exists.not
117
+ end
118
+ private_class_method :none
119
+
120
+ # A version that carries its own id as its number, which is the number
121
+ # of the version of `table`.
122
+ #: (untyped, String, untyped) -> untyped
123
+ def self.numbering(anchor, primary_key, table)
124
+ id = anchor[primary_key]
125
+ id.eq(table[:transaction_id]).and(anchor[:transaction_id].eq(id))
126
+ end
127
+ private_class_method :numbering
128
+
129
+ # An anchor saved after the version and before the start, or after the
130
+ # start and no later than the version.
131
+ #: (untyped, untyped, Time) -> untyped
132
+ def self.between(anchor_at, version_at, start)
133
+ anchor_at.gt(version_at).and(anchor_at.lt(start))
134
+ .or(anchor_at.gteq(start).and(anchor_at.lteq(version_at)))
135
+ end
136
+ private_class_method :between
137
+ end
138
+ end