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
@@ -2,340 +2,80 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Moves each edge of a wall-clock window that falls inside one of a root's
6
- # transactions back to where that transaction began, so the transaction is
7
- # wholly in the later window.
5
+ # Answers where a range of versions really starts: where the transactions
6
+ # of its roots' first versions began (`range_start`).
8
7
  #
9
8
  # PT-AT reads a root's associations at the start of the transaction of the
10
- # root version it reifies. A window starting just after a child saved its
11
- # part of such a transaction therefore starts from the state before that
12
- # child's change, and one ending there ends at it too, so the change belonged
13
- # to no window and surfaced at the next transaction, under its author.
14
- #
15
- # Only the root's own versions on either side of an edge are consulted:
16
- # rows locked by an update keep two transactions of one root from
17
- # interleaving, so a transaction holding a root version and crossing the edge
18
- # holds the root's nearest version on one side of it. One that saved the root
19
- # after the edge moves it. One that saved the root only before the edge moves
20
- # it only when it saved a record of a type on the requested paths after it,
21
- # which the root's history reads: without one, the root's change is in the
22
- # earlier window, where its version is, as selecting by a window's versions
23
- # finds it, and ScopedRootSelection selects the roots such a move brings into
24
- # a window. Each edge is moved from where it was asked for, never from where
25
- # another edge moved, so adjacent windows move their shared edge alike.
26
- module TransactionCut # rubocop:disable Metrics/ModuleLength
27
- # One edge of a window. A strict edge keeps versions recorded at its
28
- # instant on the left, as an inclusive end does. A plain class rather than
29
- # Data.define, which arrived in Ruby 3.2 while this gem supports 3.1.
30
- class Edge
31
- # A window's start, which keeps versions recorded at it on the right.
32
- #: (TimeRange) -> Edge
33
- def self.start_of(range) = new(range.begin_time, false)
34
-
35
- # A window's end, strict when the window includes it; an endless window
36
- # has none.
37
- #: (TimeRange) -> Edge?
38
- def self.end_of(range)
39
- finish = range.end_time
40
- new(finish, !range.exclude_end?) if finish
41
- end
42
-
43
- #: (Time, bool) -> void
44
- def initialize(time, strict)
45
- @time = time
46
- @strict = strict
47
- freeze
48
- end
49
-
50
- #: (untyped) -> untyped
51
- def left(column)
52
- @strict ? column.lteq(@time) : column.lt(@time)
53
- end
54
-
55
- #: (untyped) -> untyped
56
- def right(column)
57
- @strict ? column.gt(@time) : column.gteq(@time)
58
- end
59
-
60
- # @rbs @time: Time
61
- # @rbs @strict: bool
62
- end
63
-
64
- # The same as `windows` for a batch of roots, keyed by identity.
65
- #: (Array[untyped], TimeRange?, ?traversal: AssociationTraversal?) -> Hash[Array[String], TimeRange]
66
- def self.batch_windows(records, range, traversal: nil)
67
- return {} unless range
68
-
69
- moved = {} #: Hash[Array[String], TimeRange]
70
- records.group_by(&:class).each_with_object(moved) do |(model_class, group), by_identity|
71
- identities = group.to_h { |record| [record.id.to_s, Endpoint.identity(record)] }
72
- windows(model_class, group, range, traversal: traversal).each do |id, window|
73
- by_identity[identities.fetch(id)] = window
74
- end
75
- end
76
- end
77
-
78
- # Where history for a batch must be read from: the earliest moved start.
79
- #: (TimeRange?, Hash[Array[String], TimeRange]) -> Time?
80
- def self.earliest_start(range, windows)
81
- return unless range
82
-
83
- [range.begin_time, *windows.each_value.map(&:begin_time)].min
84
- end
85
-
86
- # The windows that move, keyed by root id. A root missing from the result
87
- # keeps the window as asked. `traversal` names the requested paths.
88
- # `records` may be ids. Each move is reported unless `report` is false,
89
- # for a reader that looks before the analysis that reports them.
90
- #: (untyped, Array[untyped], TimeRange, ?traversal: AssociationTraversal?, ?report: bool) -> Hash[String, TimeRange]
91
- def self.windows(model_class, records, range, traversal: nil, report: true)
92
- versions = transaction_versions(model_class)
93
- return {} unless versions
94
-
95
- types = traversal&.path_types(model_class) || []
96
- starts = moved_edges(versions, records, Edge.start_of(range), types)
97
- finish = Edge.end_of(range)
98
- ends = finish ? moved_edges(versions, records, finish, types) : {} #: Hash[String, Time]
99
- (starts.keys | ends.keys).to_h do |id|
100
- window = moved(range, starts[id], ends[id])
101
- report_move(model_class, id, range, window) if report
102
- [id, window]
9
+ # root version it reifies, so a range that starts at a version starts
10
+ # before whatever that version's transaction saved earlier. A wall-clock
11
+ # window does not move: it reports the transactions that end inside it
12
+ # (see TransactionEnds and CrossingTransactions).
13
+ module TransactionCut
14
+ # A range starting at a version starts before that version's transaction,
15
+ # as PT-AT reads associations there. A version saved earlier in the same
16
+ # transaction, such as the child update behind a `touch: true` parent
17
+ # version, can be recorded before the start, so the start moves back to
18
+ # where each root's first transaction in the range began. History loaded
19
+ # from the start alone would read that child after its change.
20
+ #: (Array[untyped], untyped) -> untyped
21
+ def self.range_start(root_versions, start_at)
22
+ began = opening_versions(root_versions, start_at)
23
+ .each_slice(Support::IDS_PER_STATEMENT).map do |slice|
24
+ transaction_start(slice, start_at)
103
25
  end
26
+ [start_at, *began.compact].min
104
27
  end
105
28
 
106
- # Reads the windows of `model_class` ids for a range, unreported.
107
- #: (untyped, AssociationTraversal?) -> ^(Array[String], TimeRange) -> Hash[String, TimeRange]
108
- def self.reader(model_class, traversal)
109
- ->(ids, range) { windows(model_class, ids, range, traversal: traversal, report: false) }
110
- end
111
-
112
- # A transaction holds its rows only while it runs, so in history as an
113
- # application saves it an edge moves by moments. A longer move means a
114
- # long transaction or rewritten times, which only the application can
115
- # judge, so each move is reported rather than logged or refused.
116
- #: (untyped, String, TimeRange, TimeRange) -> void
117
- def self.report_move(model_class, id, range, window)
118
- Instrumentation.notify(
119
- 'moved_window',
120
- item_type: model_class.base_class.name, item_id: id,
121
- requested: range.to_range, window: window.to_range
122
- )
123
- end
124
- private_class_method :report_move
125
-
126
- # The model's versions in a window, and those saved before it in a
127
- # transaction that saved a record of one of `types` inside it, which
128
- # moves their root's window back to take them in: the versions that
129
- # select a root for the window. Without a window, every version does.
130
- #: (untyped, TimeRange?, Array[String]) -> untyped
131
- def self.window_versions(model_class, range, types)
132
- versions = VersionQuery.for_model(model_class)
133
- return versions unless range
134
-
135
- inside = range.scope(versions)
136
- version_class = model_class.paper_trail.version_class
137
- return inside if types.empty? || !transactional?(version_class)
138
-
139
- inside.or(crossing_versions(versions, version_class, range, types))
140
- end
141
-
142
- #: (untyped, untyped, TimeRange, Array[String]) -> untyped
143
- def self.crossing_versions(versions, version_class, range, types)
144
- transactions = range.scope(version_class.where(item_type: types)).select(:transaction_id)
145
- versions.where(version_class.arel_table[:created_at].lt(range.begin_time))
146
- .where(transaction_id: transactions)
29
+ # The range then reads as a window from there would (see TransactionEnds):
30
+ # a transaction open where it starts takes effect where it ends, so what
31
+ # it saved before is read from where it began, in the version tables of
32
+ # the model and its paths.
33
+ #: (untyped, AssociationTraversal, untyped) -> untyped
34
+ def self.crossing_start(model, traversal, start_at)
35
+ traversal.reach_before(model, start_at) || start_at
147
36
  end
148
- private_class_method :crossing_versions
149
37
 
38
+ # A range that ends at a version ends where that version's transaction
39
+ # takes effect, at the last version it saved (see TransactionEnds), so
40
+ # what another transaction saved and committed before then is read, and
41
+ # a destroyed root's tree is read up to its destruction.
150
42
  #: (untyped) -> untyped
151
- def self.transaction_versions(model_class)
152
- VersionQuery.for_model(model_class) if transactional?(model_class.paper_trail.version_class)
153
- end
154
- private_class_method :transaction_versions
155
-
156
- #: (untyped) -> bool
157
- def self.transactional?(version_class)
158
- version_class.column_names.include?('transaction_id')
159
- end
160
- private_class_method :transactional?
161
-
162
- # Each root's earliest start among its transactions that cross the edge:
163
- # the one that saved its first version after the edge, which crosses when
164
- # it began before it, and the one that saved its last version before it,
165
- # which crosses when it saved a record of one of `types` after it.
166
- #: (untyped, Array[untyped], Edge, Array[String]) -> Hash[String, Time]
167
- def self.moved_edges(versions, records, edge, types)
168
- moved = {} #: Hash[String, Time]
169
- crossing(versions, records, edge, types).each_with_object(moved) do |(roots, starts), found|
170
- starts.each do |transaction, start|
171
- roots.fetch(transaction).each { |id| found[id] = [found[id], start].compact.min }
172
- end
173
- end
174
- end
175
- private_class_method :moved_edges
176
-
177
- # For each side of the edge, the roots its transactions hold next to the
178
- # edge, and where those that cross it began.
179
- #: (untyped, Array[untyped], Edge, Array[String]) -> Array[[Hash[untyped, Array[String]], Hash[untyped, Time]]]
180
- def self.crossing(versions, records, edge, types)
181
- later, earlier = nearest_roots(versions, records, edge)
182
- # @type var sides: Array[[Hash[untyped, Array[String]], Hash[untyped, Time]]]
183
- sides = [[later, crossing_starts(versions.klass, later.keys, edge)]]
184
- return sides if types.empty?
185
-
186
- sides << [earlier, crossing_starts(versions.klass, earlier.keys, edge, types)]
187
- end
188
- private_class_method :crossing
189
-
190
- # The roots whose versions next to the edge each transaction holds, those
191
- # after the edge and those before it.
192
- #: (untyped, Array[untyped], Edge) -> [Hash[untyped, Array[String]], Hash[untyped, Array[String]]]
193
- def self.nearest_roots(versions, records, edge)
194
- # The lookup names its ids twice in one statement, for the grouped instants
195
- # and for the versions they join, so half a statement's ids keep it under
196
- # 1,000 bound parameters, the most SQLite allowed before 3.32.
197
- rows = records.each_slice(Support::IDS_PER_STATEMENT / 2).flat_map do |slice|
198
- nearest(versions, slice, edge)
199
- end
200
- later, earlier = rows.partition(&:last)
201
- [by_transaction(later), by_transaction(earlier)]
202
- end
203
- private_class_method :nearest_roots
204
-
205
- # The roots of the rows, by the transaction each row names.
206
- #: (Array[[String, untyped, bool]]) -> Hash[untyped, Array[String]]
207
- def self.by_transaction(rows)
208
- rows.group_by { |row| row.fetch(1) }.transform_values { |group| group.map(&:first) }
209
- end
210
- private_class_method :by_transaction
211
-
212
- # Each root's nearest versions on either side of an edge, as [id,
213
- # transaction, after the edge] rows; versions tied at the nearest instant
214
- # are all kept. One statement per slice: a grouped pass over the roots'
215
- # versions finds both instants, and a join reads the versions saved at
216
- # either. A lookup per root, joined by UNION ALL, took SQL Server about a
217
- # second per 200 roots to compile. Rows read without a model come back as
218
- # the adapter returns them, so the transaction is cast as the grouped
219
- # query's keys are.
220
- #
221
- # The ids go to the adapter as bound parameters. Written into the
222
- # statement, they made each slice's text new to SQL Server, which compiled
223
- # it again, at about 0.05 ms per id.
224
- #: (untyped, Array[untyped], Edge) -> Array[[String, untyped, bool]]
225
- def self.nearest(versions, records, edge)
226
- transaction = versions.type_for_attribute('transaction_id')
227
- rows = versions.connection.select_rows(nearest_query(versions, records, edge))
228
- rows.map { |id, value, flag| [id.to_s, transaction.cast(value), after_edge?(flag)] }
229
- end
230
- private_class_method :nearest
231
-
232
- # The roots' versions saved in a transaction at either nearest instant,
233
- # each with whether it is the one after the edge.
234
- #: (untyped, Array[untyped], Edge) -> untyped
235
- def self.nearest_query(versions, records, edge)
236
- own = versions.where(item_id: records)
237
- table = own.arel_table
238
- instants = nearest_instants(own, edge)
239
- own.joins(Support.arel::Nodes::InnerJoin.new(instants, at_either(table, instants)))
240
- .where.not(transaction_id: nil)
241
- .select(table[:item_id], table[:transaction_id], after_edge(table, instants)).arel
242
- end
243
- private_class_method :nearest_query
244
-
245
- # 1 for a version saved at the instant after the edge, 0 for one before.
246
- # Only the 1 is read (see after_edge?), so another value or alias, or none,
247
- # answers the same.
248
- # mutant:disable
249
- #: (untyped, untyped) -> untyped
250
- def self.after_edge(table, instants)
251
- Support.arel::Nodes::Case.new.when(table[:created_at].eq(instants[:after_at]))
252
- .then(1).else(0).as('after_edge')
253
- end
254
- private_class_method :after_edge
255
-
256
- # Whether after_edge flagged a row as saved after the edge. Adapters
257
- # return the flag as an Integer or a String, so any spelling that reads
258
- # only 1 as after answers the same.
259
- # mutant:disable
260
- #: (untyped) -> bool
261
- def self.after_edge?(flag)
262
- flag.to_i == 1
263
- end
264
- private_class_method :after_edge?
265
-
266
- # Each root's latest instant before the edge and earliest after it, from
267
- # every version, saved in a transaction or not.
268
- #: (untyped, Edge) -> untyped
269
- def self.nearest_instants(own, edge)
270
- table = own.arel_table
271
- column = table[:created_at]
272
- nodes = Support.arel::Nodes
273
- before = side_instant(nodes::Max, edge.left(column), column).as('before_at')
274
- after = side_instant(nodes::Min, edge.right(column), column).as('after_at')
275
- own.group(:item_id).select(table[:item_id], before, after).arel.as('paper_trail_diff_nearest')
276
- end
277
- private_class_method :nearest_instants
278
-
279
- # The latest or earliest of the times on one side of the edge.
280
- #: (untyped, untyped, untyped) -> untyped
281
- def self.side_instant(aggregate, side, column)
282
- aggregate.new([Support.arel::Nodes::Case.new.when(side).then(column)])
283
- end
284
- private_class_method :side_instant
285
-
286
- # The same root's versions saved at either of its instants.
287
- #: (untyped, untyped) -> untyped
288
- def self.at_either(table, instants)
289
- column = table[:created_at]
290
- at_either = column.eq(instants[:before_at]).or(column.eq(instants[:after_at]))
291
- Support.arel::Nodes::On.new(table[:item_id].eq(instants[:item_id]).and(at_either))
292
- end
293
- private_class_method :at_either
294
-
295
- # Where each transaction that saved a version before the edge began; with
296
- # `types`, only one that also saved a record of one of them after it.
297
- #: (untyped, Array[untyped], Edge, ?Array[String]?) -> Hash[untyped, Time]
298
- def self.crossing_starts(version_class, transactions, edge, types = nil)
299
- table = version_class.arel_table
300
- earlier = edge.left(table[:created_at])
301
- starts = {} #: Hash[untyped, Time]
302
- transactions.each_slice(Support::IDS_PER_STATEMENT).with_object(starts) do |slice, found|
303
- crossing = version_class.where(transaction_id: slice).where(earlier)
304
- if types
305
- crossing = crossing.where(transaction_id: saved_later(version_class, slice, edge, types))
306
- end
307
- found.merge!(crossing.group(:transaction_id).minimum(:created_at))
308
- end
309
- end
310
- private_class_method :crossing_starts
311
-
312
- # Those of the transactions that saved a version of a record of one of
313
- # `types` on the edge's later side. A subquery apart from the outer one,
314
- # rather than an EXISTS correlated with it, so the database finds them
315
- # once by transaction: SQLite answered the correlated form by scanning
316
- # every later version of the types for each version before the edge, with
317
- # the README's indexes 17 s for 450 transactions on 114,000 versions.
318
- # Only the outer query's transactions are read, so the database can find
319
- # them by transaction rather than read every later version of the types;
320
- # the outer query keeps only those anyway, so no spec can tell the
321
- # mutation that drops them apart.
322
- # mutant:disable
323
- #: (untyped, Array[untyped], Edge, Array[String]) -> untyped
324
- def self.saved_later(version_class, transactions, edge, types)
325
- version_class.where(transaction_id: transactions, item_type: types)
326
- .where(edge.right(version_class.arel_table[:created_at]))
327
- .select(:transaction_id)
328
- end
329
- private_class_method :saved_later
330
-
331
- #: (TimeRange, Time?, Time?) -> TimeRange
332
- def self.moved(range, start, finish)
333
- begin_time = start || range.begin_time
334
- return TimeRange.new(begin_time...[finish, begin_time].max) if finish
335
- return TimeRange.new(begin_time...range.end_time) if range.exclude_end?
336
-
337
- TimeRange.new(begin_time..range.end_time)
338
- end
339
- private_class_method :moved
43
+ def self.range_end(version)
44
+ key = ActivityTransactionGroups.transaction_key(version) #: untyped
45
+ RecordedTransactionEnds.new.call([version]) { [] }.fetch(key, version)
46
+ end
47
+
48
+ # When ranges ending at these versions all end (see range_end): the
49
+ # latest time any of their transactions takes effect; nil for none.
50
+ #: (Array[untyped]) -> untyped
51
+ def self.ends_at(versions)
52
+ recorded = RecordedTransactionEnds.new.call(versions) { [] }
53
+ (versions + recorded.values).map(&:created_at).max
54
+ end
55
+
56
+ # Each root's first version at or after the start, where a transaction
57
+ # saved it.
58
+ #: (Array[untyped], untyped) -> Array[untyped]
59
+ def self.opening_versions(root_versions, start_at)
60
+ return [] unless start_at
61
+
62
+ root_versions.reject { |version| version.created_at < start_at }
63
+ .sort_by { |version| Support.chronological_version_key(version) }
64
+ .uniq { |version| Endpoint.identity(version) }
65
+ .select { |version| VersionBoundary.transaction_id(version) }
66
+ end
67
+ private_class_method :opening_versions
68
+
69
+ # When the earliest of the transactions of these versions began. Of
70
+ # transactions that share a number, only the one each version is in
71
+ # counts (see TransactionAnchors).
72
+ #: (Array[untyped], untyped) -> untyped
73
+ def self.transaction_start(versions, start_at)
74
+ version_class = versions.first.class
75
+ numbers = versions.map { |version| VersionBoundary.transaction_id(version) }
76
+ TransactionAnchors.continued(version_class.where(transaction_id: numbers), version_class,
77
+ start_at, versions).minimum(:created_at)
78
+ end
79
+ private_class_method :transaction_start
340
80
  end
341
81
  end
@@ -0,0 +1,194 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Where each transaction of a root's timeline takes effect: at the last
6
+ # version it saved, of any record, as `recorded` holds it (see
7
+ # RecordedTransactionEnds), or among the timeline's own versions where a
8
+ # number is shared (see TransactionAnchors). A root read without its
9
+ # associations is read without them: its versions take effect where they
10
+ # were saved, since row locks keep two transactions from interleaving the
11
+ # versions of one record.
12
+ #
13
+ # Two transactions that save in one tree at the same time interleave their
14
+ # versions, yet neither sees what the other has not committed, and one may
15
+ # undo its own changes before it ends, such as a comment it created and
16
+ # deleted again. Rows locked by a write keep two open transactions from
17
+ # saving one record, so wherever the order of two transactions matters, the
18
+ # one that saved its last version first also ended first. A timeline that
19
+ # places every version of a transaction at its last one therefore reads the
20
+ # transactions one after another, as if none had overlapped: a record reads
21
+ # as it stood before every transaction that had not ended yet, and each
22
+ # change is reported with its own transaction's.
23
+ #
24
+ # A version saved outside a transaction takes effect where it was saved.
25
+ #
26
+ # Every history, of a window or of a range of versions, is read from where
27
+ # the transactions open at its start began (see PreparedHistoryLoader), so
28
+ # what a root reports does not depend on what else a batch read with it.
29
+ class TransactionEnds
30
+ #: (Array[untyped], ?Hash[Array[untyped], untyped]?) -> void
31
+ def initialize(versions, recorded = nil)
32
+ @recorded = recorded
33
+ saved = versions.sort_by { |version| Support.chronological_version_key(version) }
34
+ @last = TransactionEnds.lasts(saved)
35
+ @held = [] #: Array[untyped]
36
+ freeze
37
+ end
38
+
39
+ # The last of the versions of each transaction, and of those outside one,
40
+ # by transaction key.
41
+ #: (Array[untyped]) -> Hash[Array[untyped]?, untyped]
42
+ def self.lasts(saved)
43
+ saved.group_by { |version| ActivityTransactionGroups.transaction_key(version) }
44
+ .transform_values(&:last)
45
+ end
46
+
47
+ # The last version of the version's transaction, or the version itself.
48
+ #: (untyped) -> untyped
49
+ def last(version)
50
+ recorded = @recorded
51
+ key = ActivityTransactionGroups.transaction_key(version)
52
+ return version if key.nil? || recorded.nil?
53
+
54
+ recorded[key] || @last[key] || version
55
+ end
56
+
57
+ # Where a boundary takes effect, and when: at the last version of a
58
+ # version's transaction, or where a live record was read, since no
59
+ # transaction is keyed by a model that is not a version class. Every
60
+ # record of a snapshot is read at one boundary, so the last answer is
61
+ # kept.
62
+ #: (untyped) -> [untyped, untyped]
63
+ def target(boundary)
64
+ held = @held
65
+ return held.fetch(1) if !held.empty? && held.fetch(0).equal?(boundary)
66
+
67
+ target = last(boundary)
68
+ answer = [target, target.created_at] #: [untyped, untyped]
69
+ held.replace([boundary, answer])
70
+ answer
71
+ end
72
+
73
+ # Orders versions by where their transactions end, then as they were
74
+ # saved.
75
+ #: (untyped) -> Array[untyped]
76
+ def sort_key(version)
77
+ [Support.chronological_version_key(last(version)),
78
+ Support.chronological_version_key(version)]
79
+ end
80
+
81
+ # @rbs @recorded: Hash[Array[untyped], untyped]?
82
+ # @rbs @last: Hash[Array[untyped]?, untyped]
83
+ # @rbs @held: Array[untyped]
84
+ end
85
+
86
+ # Reads where transactions end from their version tables: the last version
87
+ # each saved there, of any record.
88
+ #
89
+ # A transaction can go on to save a record a timeline does not hold, such
90
+ # as one it moved out of the tree, and which records a timeline holds
91
+ # depends on where it is read from. Were a transaction placed at the last
92
+ # of the versions held, two windows could place it differently, and what it
93
+ # did would be reported in neither or in both.
94
+ #
95
+ # The versions held are asked about together, a statement for 500
96
+ # transactions, and one more for those whose last version is not held.
97
+ # The last version is the latest dated, ids breaking a tie, as every
98
+ # window compares versions by date: a callback that saves other records
99
+ # before its own version dates that one first, as its save began. A number
100
+ # that transactions of two version tables took is not read (see
101
+ # TransactionAnchors), and its versions are placed at the last held.
102
+ class RecordedTransactionEnds
103
+ #: () -> void
104
+ def initialize
105
+ @ends = {} #: Hash[Array[untyped], untyped]
106
+ @asked = Set.new #: Set[Array[untyped]]
107
+ end
108
+
109
+ # The last version of each transaction asked about so far, by transaction
110
+ # key, once those of `versions` are among them. They are asked about along
111
+ # with every version the block returns, so that a history is read at once.
112
+ # A version saved outside a transaction is read beside the history's
113
+ # others, wherever their transactions end, so it asks about them all; a
114
+ # live record asks nothing.
115
+ #: (Array[untyped]) { () -> Array[untyped] } -> Hash[Array[untyped], untyped]
116
+ def call(versions)
117
+ ask(versions + yield) unless versions.all? { |version| answered?(version) }
118
+ @ends
119
+ end
120
+
121
+ private
122
+
123
+ # @rbs @ends: Hash[Array[untyped], untyped]
124
+ # @rbs @asked: Set[Array[untyped]]
125
+
126
+ #: (untyped) -> bool
127
+ def answered?(version)
128
+ key = ActivityTransactionGroups.transaction_key(version)
129
+ key ? @asked.include?(key) : !VersionBoundary.version_record?(version)
130
+ end
131
+
132
+ #: (untyped) -> bool
133
+ def asked?(version)
134
+ key = ActivityTransactionGroups.transaction_key(version)
135
+ key.nil? || @asked.include?(key)
136
+ end
137
+
138
+ #: (Array[untyped]) -> void
139
+ def ask(versions)
140
+ versions.reject { |version| asked?(version) }.group_by(&:class).each do |version_class, held|
141
+ by_number = held.group_by { |version| VersionBoundary.transaction_id(version) }
142
+ by_number.each_key { |number| @asked << [version_class.name, number] }
143
+ by_number.keys.each_slice(Support::IDS_PER_STATEMENT) do |numbers|
144
+ read(version_class, numbers - TransactionAnchors.shared(version_class, numbers),
145
+ by_number)
146
+ end
147
+ end
148
+ end
149
+
150
+ # Notes the last version of each of these transactions: the one held
151
+ # where it is, and the one read otherwise.
152
+ #: (untyped, Array[untyped], Hash[untyped, Array[untyped]]) -> void
153
+ def read(version_class, numbers, held)
154
+ last = latest(version_class, numbers)
155
+ known = held.fetch_values(*last.keys).flatten + other(version_class, last, held)
156
+ known.select { |version| version.id == last.fetch(version.transaction_id) }
157
+ .group_by(&:transaction_id).each do |number, versions|
158
+ @ends[[version_class.name, number]] = versions.first
159
+ end
160
+ end
161
+
162
+ # The id of each transaction's last version: of those dated latest, the
163
+ # one versions sort last by id.
164
+ #: (untyped, Array[untyped]) -> Hash[untyped, untyped]
165
+ def latest(version_class, numbers)
166
+ table = version_class.arel_table
167
+ rows = version_class.where(transaction_id: numbers)
168
+ .where(table[:created_at].eq(newest(table)))
169
+ .pluck(:transaction_id, version_class.primary_key)
170
+ rows.group_by(&:first).transform_values do |tied|
171
+ tied.map(&:last).max_by { |id| Support.version_key(nil, id) }
172
+ end
173
+ end
174
+
175
+ # When the transaction of a version of `table` saved its latest dated.
176
+ #: (untyped) -> untyped
177
+ def newest(table)
178
+ dated = table.alias
179
+ Support.arel::SelectManager.new.from(dated).project(dated[:created_at].maximum)
180
+ .where(dated[:transaction_id].eq(table[:transaction_id]))
181
+ end
182
+
183
+ # The last versions not held, read only for what places them. With
184
+ # none missing, the relation reads nothing.
185
+ #: (untyped, Hash[untyped, untyped], Hash[untyped, Array[untyped]]) -> Array[untyped]
186
+ def other(version_class, last, held)
187
+ missing = last.reject do |number, id|
188
+ held.fetch(number).any? { |version| version.id == id }
189
+ end
190
+ version_class.where(version_class.primary_key => missing.values)
191
+ .select(version_class.primary_key, :created_at, :transaction_id)
192
+ end
193
+ end
194
+ end