paper_trail_diff 0.15.0 → 0.17.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 (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +724 -1
  3. data/README.md +43 -8
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +89 -32
  6. data/docs/reference.md +427 -96
  7. data/docs/testing.md +260 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -11
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +49 -18
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +13 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +104 -52
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +200 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +39 -6
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +22 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +41 -42
  44. data/lib/paper_trail_diff/change_attribution.rb +314 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -33
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +29 -10
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +8 -7
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +119 -87
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +182 -50
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +31 -36
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +47 -12
  73. data/lib/paper_trail_diff/prepared_record_index.rb +143 -49
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +99 -0
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +92 -32
  84. data/lib/paper_trail_diff/scope_ranking.rb +27 -34
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +18 -7
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +65 -39
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +40 -22
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +9 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +235 -75
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +41 -23
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +36 -1
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +32 -44
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +25 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +55 -10
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +125 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +26 -5
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +16 -4
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -9
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +9 -3
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +19 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +113 -17
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +15 -13
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +70 -15
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +62 -0
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -9
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +16 -16
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +40 -12
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -7
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +131 -40
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +17 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +31 -7
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -52,7 +52,8 @@ module PaperTrailDiff
52
52
  id = owner.attributes[reflection.foreign_key.to_s]
53
53
  return [true, []] if id.nil?
54
54
 
55
- model_class = target_class(owner, reflection)
55
+ type = owner.attributes[reflection.foreign_type]
56
+ model_class = AssociationTraversal.stored_target(reflection, type)
56
57
  return [false, []] unless model_class &&
57
58
  @conditions.call(reflection, model_class, ranked: ranked)
58
59
 
@@ -60,13 +61,6 @@ module PaperTrailDiff
60
61
  [handled, state && in_scope?(state, reflection, ranked, model_class) ? [state] : []]
61
62
  end
62
63
 
63
- #: (PreparedRecordState, untyped) -> untyped
64
- def target_class(owner, reflection)
65
- return reflection.klass unless reflection.polymorphic?
66
-
67
- AssociationTraversal.named_class(owner.attributes[reflection.foreign_type].to_s)
68
- end
69
-
70
64
  # The members of each join record the owner had at the boundary, as
71
65
  # PreparedHistory#through_records reads them from records. Under
72
66
  # `source_type:`, only join records of that type count. A has_many
@@ -118,35 +112,39 @@ module PaperTrailDiff
118
112
  [model.base_class.name, *Array(model.primary_key).map { |key| state.attributes[key].to_s }]
119
113
  end
120
114
 
115
+ # The scope's condition and the owner's id are read once for all the
116
+ # owner's children, which are read at every boundary.
121
117
  #: (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
122
118
  def children(owner, reflection, boundary, ranked)
119
+ condition = @conditions.call(reflection, ranked: ranked) #: ScopeCondition
120
+ owner_id = owner_id(owner)
123
121
  selected = [] #: Array[PreparedRecordState]
124
122
  @edges.call(owner.model_class, reflection).each_value do |group|
125
- ids_for(group, owner).each do |id|
123
+ ids_for(group, owner_id).each do |id|
126
124
  handled, child = @records.snapshot_state_before(group.fetch(:model), id, boundary)
127
125
  return [false, []] unless handled
128
126
 
129
- selected << child if child && member?(child, owner, reflection, ranked)
127
+ selected << child if child && member?(child, owner, owner_id, reflection, condition)
130
128
  end
131
129
  end
132
130
  return [true, selected] unless ranked
133
131
 
134
- condition = @conditions.call(reflection) #: ScopeCondition
135
132
  [true, first_if_one(reflection, condition.rank(selected))]
136
133
  end
137
134
 
138
- #: (untyped, PreparedRecordState) -> Array[untyped]
139
- def ids_for(group, owner)
135
+ #: (untyped, String) -> Array[untyped]
136
+ def ids_for(group, owner_id)
140
137
  owners = group[:owners]
141
138
  empty = [] #: Array[untyped]
142
- owners ? owners.fetch(owner_id(owner), empty) : group.fetch(:ids)
139
+ owners ? owners.fetch(owner_id, empty) : group.fetch(:ids)
143
140
  end
144
141
 
145
- #: (PreparedRecordState, PreparedRecordState, untyped, bool) -> bool
146
- def member?(child, owner, reflection, ranked)
147
- return false unless child.attributes[reflection.foreign_key.to_s].to_s == owner_id(owner)
148
- return false unless AssociationTraversal.sti_member?(reflection.klass, child.attributes)
149
- return false unless in_scope?(child, reflection, ranked)
142
+ #: (PreparedRecordState, PreparedRecordState, String, untyped, ScopeCondition) -> bool
143
+ def member?(child, owner, owner_id, reflection, condition)
144
+ attributes = child.attributes
145
+ return false unless attributes[reflection.foreign_key.to_s].to_s == owner_id
146
+ return false unless AssociationTraversal.sti_member?(reflection.klass, attributes)
147
+ return false unless condition.matches?(attributes)
150
148
  return true unless reflection.options[:as]
151
149
 
152
150
  matching_type?(child, owner.model_class, reflection)
@@ -0,0 +1,99 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Runs one read's statements inside one database snapshot. Without one, a row
6
+ # that commits between two statements of the read can be seen by one of them
7
+ # and missed by another: an activity read then found a comment whose versions
8
+ # it had not read yet, and raised `KeyError`.
9
+ #
10
+ # PostgreSQL and MySQL (through mysql2 or trilogy), and adapters built on
11
+ # them such as PostGIS, run the read at REPEATABLE READ, which gives every
12
+ # statement of the transaction the same view. SQL Server runs it at SNAPSHOT
13
+ # when the database allows that isolation level, which it does only after
14
+ # `ALTER DATABASE ... SET ALLOW_SNAPSHOT_ISOLATION ON`; otherwise SNAPSHOT
15
+ # raises, so it takes none. Other adapters get no snapshot; docs/reference.md
16
+ # lists them under limitations.
17
+ module ReadSnapshot
18
+ # The adapters whose subclasses take a snapshot, by name, since an
19
+ # application loads only the adapters it uses.
20
+ SNAPSHOT_ADAPTERS = %w[
21
+ ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
22
+ ActiveRecord::ConnectionAdapters::AbstractMysqlAdapter
23
+ ].freeze
24
+ SQL_SERVER_ADAPTER = 'ActiveRecord::ConnectionAdapters::SQLServerAdapter'
25
+
26
+ # 1 is ON. The setting can change while the application runs, so it is
27
+ # read for each call; the catalog answers at once.
28
+ SQL_SERVER_SNAPSHOT_STATE =
29
+ 'SELECT snapshot_isolation_state FROM sys.databases WHERE database_id = DB_ID()'
30
+
31
+ # Yields once. Each connection the values read through gets a snapshot
32
+ # transaction first, unless that connection already has a transaction open:
33
+ # its isolation level belongs to the caller, and this gem cannot change it.
34
+ # A value may be a model class, a relation, a record, or a version. Any
35
+ # other value reads no table and is ignored.
36
+ #: (Array[untyped]) { () -> untyped } -> untyped
37
+ def self.call(values, &block)
38
+ classes = connection_classes(values)
39
+ classes.reverse_each.reduce(block) do |inner, klass|
40
+ connection = klass.connection
41
+ level = isolation(connection) unless connection.transaction_open?
42
+ next inner unless level
43
+
44
+ -> { klass.transaction(isolation: level) { inner.call } }
45
+ end.call
46
+ end
47
+
48
+ # The isolation level that gives this connection's statements one view, or
49
+ # nil when it has none.
50
+ #: (untyped) -> Symbol?
51
+ def self.isolation(connection)
52
+ return :repeatable_read if adapter?(connection, SNAPSHOT_ADAPTERS)
53
+
54
+ :snapshot if adapter?(connection, [SQL_SERVER_ADAPTER]) && sql_server_snapshot?(connection)
55
+ end
56
+
57
+ #: (untyped, Array[String]) -> bool
58
+ def self.adapter?(connection, names)
59
+ connection.class.ancestors.any? { |ancestor| names.include?(ancestor.name) }
60
+ end
61
+
62
+ # Named as a schema query, as Active Record names its own catalog reads.
63
+ #: (untyped) -> bool
64
+ def self.sql_server_snapshot?(connection)
65
+ connection.select_value(SQL_SERVER_SNAPSHOT_STATE, 'SCHEMA').to_i == 1
66
+ end
67
+
68
+ # One class per connection: each read model and its version class, with the
69
+ # repeats through a shared connection dropped. An associated model on
70
+ # another database is not among them, so it is read outside the snapshot.
71
+ #: (Array[untyped]) -> Array[untyped]
72
+ def self.connection_classes(values)
73
+ values.filter_map { |value| model_for(value) }
74
+ .flat_map { |model| [model, model.paper_trail.version_class] }
75
+ .uniq(&:connection)
76
+ end
77
+
78
+ # The versioned model a value reads from, or nil.
79
+ #: (untyped) -> untyped
80
+ def self.model_for(value)
81
+ model = case value
82
+ when Support.constant('ActiveRecord::Relation') then value.klass
83
+ when Class then value
84
+ else endpoint_model(value)
85
+ end
86
+ model if Support.versioned?(model)
87
+ end
88
+
89
+ # A version reads the model of its item; anything else its own class,
90
+ # which is a versioned model only for a record.
91
+ #: (untyped) -> untyped
92
+ def self.endpoint_model(value)
93
+ Endpoint.version?(value) ? Endpoint.model_class(value) : value.class
94
+ end
95
+
96
+ private_class_method :isolation, :adapter?, :sql_server_snapshot?, :model_for,
97
+ :endpoint_model
98
+ end
99
+ end
@@ -39,7 +39,7 @@ module PaperTrailDiff
39
39
  changes = ActivityEventRecordResolver.new.deserialized_changeset(@version, model_class)
40
40
  return if changes.nil?
41
41
 
42
- value_changes(changes, Array(model_class.primary_key) + ignored)
42
+ value_changes(model_class, changes, Array(model_class.primary_key) + ignored)
43
43
  end
44
44
 
45
45
  private
@@ -68,16 +68,15 @@ module PaperTrailDiff
68
68
  end
69
69
 
70
70
  # Primary keys identify the record rather than describe it, as in a diff.
71
- #: (untyped, Array[String]) -> Hash[String, ValueChange]
72
- def value_changes(changes, excluded)
73
- recorded = {} #: Hash[String, ValueChange]
74
- changes.each do |name, values|
75
- key = name.to_s
76
- next if excluded.include?(key)
77
-
78
- recorded[key] = ValueChange.new(from: values.first, to: values.last)
79
- end
80
- recorded.sort.to_h.freeze
71
+ # Each side is read as a step's diff reads it (see StoredValues), so a
72
+ # value compares equal to the state the change produced.
73
+ #: (untyped, untyped, Array[String]) -> Hash[String, ValueChange]
74
+ def value_changes(model_class, changes, excluded)
75
+ kept = changes.to_h { |name, values| [name.to_s, values] }.except(*excluded)
76
+ from = StoredValues.apply(model_class, kept.transform_values(&:first))
77
+ to = StoredValues.apply(model_class, kept.transform_values(&:last))
78
+ kept.keys.sort.to_h { |key| [key, ValueChange.new(from: from.fetch(key), to: to.fetch(key))] }
79
+ .freeze
81
80
  end
82
81
  end
83
82
  end
@@ -0,0 +1,60 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Decodes what each version recorded at most once per request, and only when
6
+ # a boundary's changes are read. A version many roots share in a batch, such
7
+ # as an author's, is one decode however many steps name it, and a step the
8
+ # caller never reads costs none.
9
+ class RecordedChangesReader
10
+ #: (Array[String]) -> void
11
+ def initialize(ignore)
12
+ @ignore = ignore
13
+ @changes = {} #: Hash[Array[untyped], Hash[String, ValueChange]?]
14
+ @lock = Mutex.new
15
+ end
16
+
17
+ # What `version` recorded, as PaperTrailDiff.recorded_changes returns it.
18
+ #: (untyped) -> Hash[String, ValueChange]?
19
+ def call(version)
20
+ key = Support.row_key(version)
21
+ @lock.synchronize do
22
+ @changes.fetch(key) { @changes[key] = RecordedChanges.call(version, ignore: @ignore) }
23
+ end
24
+ end
25
+
26
+ # @rbs @ignore: Array[String]
27
+ # @rbs @changes: Hash[Array[untyped], Hash[String, ValueChange]?]
28
+ # @rbs @lock: Thread::Mutex
29
+
30
+ # One boundary's recorded changes, read when first asked for. It lets go of
31
+ # the version and the reader once read, so a result keeps only what was
32
+ # decoded, and not the decodes of the whole call.
33
+ class Pending
34
+ #: (RecordedChangesReader, untyped) -> void
35
+ def initialize(reader, version)
36
+ @reader = reader
37
+ @version = version
38
+ @lock = Mutex.new
39
+ end
40
+
41
+ #: () -> Hash[String, ValueChange]?
42
+ def value
43
+ @lock.synchronize do
44
+ reader = @reader
45
+ if reader
46
+ @value = reader.call(@version)
47
+ @reader = nil
48
+ @version = nil
49
+ end
50
+ @value
51
+ end
52
+ end
53
+
54
+ # @rbs @reader: RecordedChangesReader?
55
+ # @rbs @version: untyped
56
+ # @rbs @value: Hash[String, ValueChange]?
57
+ # @rbs @lock: Thread::Mutex
58
+ end
59
+ end
60
+ end
@@ -8,46 +8,41 @@ module PaperTrailDiff
8
8
  # state before the change, or for a create, the value it was created with.
9
9
  # A version that stored neither stays on the base class.
10
10
  module RecordedClass
11
- module_function
12
-
13
11
  #: (untyped) -> untyped
14
- def for(version)
12
+ def self.for(version)
15
13
  model = Endpoint.model_class(version)
16
14
  return model unless sti_base?(model)
17
15
 
18
16
  type = stored_type(version, model).to_s
19
17
  type.empty? ? model : model.sti_class_for(type)
20
- rescue StandardError => e
21
- raise unless subclass_not_found?(e)
18
+ rescue Support.constant('ActiveRecord::SubclassNotFound')
19
+ raise InvalidEndpointError, "cannot resolve endpoint model: #{type}"
20
+ end
22
21
 
23
- raise InvalidEndpointError, "cannot resolve endpoint model: #{type}", cause: e
22
+ # The class a version recorded, or a live record's own class.
23
+ #: (untyped) -> untyped
24
+ def self.of_endpoint(endpoint)
25
+ Endpoint.version?(endpoint) ? self.for(endpoint) : endpoint.class
24
26
  end
25
27
 
26
28
  #: (untyped) -> bool
27
- def sti_base?(model)
28
- model.base_class == model && model.columns_hash.key?(model.inheritance_column.to_s)
29
+ def self.sti_base?(model)
30
+ model.base_class == model && model.columns_hash.key?(model.inheritance_column)
29
31
  end
30
32
  private_class_method :sti_base?
31
33
 
32
34
  #: (untyped, untyped) -> untyped
33
- def stored_type(version, model)
34
- column = model.inheritance_column.to_s
35
+ def self.stored_type(version, model)
36
+ column = model.inheritance_column
35
37
  if version.object
36
38
  attributes = version.object_deserialized
37
39
  return attributes.is_a?(Hash) ? attributes[column] || attributes[column.to_sym] : nil
38
40
  end
39
41
 
40
42
  changes = ActivityEventRecordResolver.new.deserialized_changeset(version, model)
41
- values = changes[column] if changes.respond_to?(:key?) && changes.key?(column)
42
- values.last if values.is_a?(Array)
43
+ values = changes[column] if changes.respond_to?(:key?)
44
+ values.last if values.instance_of?(Array)
43
45
  end
44
46
  private_class_method :stored_type
45
-
46
- #: (StandardError) -> bool
47
- def subclass_not_found?(error)
48
- active_record = Object.const_get(:ActiveRecord) #: untyped
49
- error.is_a?(active_record.const_get(:SubclassNotFound))
50
- end
51
- private_class_method :subclass_not_found?
52
47
  end
53
48
  end
@@ -0,0 +1,33 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Whether PaperTrail writes a column's changes to `object_changes` whenever
6
+ # a version saves them. Only then does a version that left a column out of
7
+ # its recorded changes show that the column changed without a version.
8
+ #
9
+ # `has_paper_trail ignore:` and `skip:` leave a column out, and `only:`
10
+ # leaves out every column it does not name. Each can also name a column
11
+ # with a condition, read when the version was saved; such a column might
12
+ # have been left out, so it is not counted as recorded either.
13
+ module RecordedColumns
14
+ #: (untyped, String?) -> bool
15
+ def self.recorded?(model_class, name)
16
+ return false unless Support.versioned?(model_class)
17
+
18
+ options = model_class.paper_trail_options
19
+ return false if named?(options.fetch(:ignore), name) || named?(options.fetch(:skip), name)
20
+
21
+ only = options.fetch(:only) #: Array[untyped]
22
+ only.empty? || only.include?(name)
23
+ end
24
+
25
+ # PaperTrail keeps each entry as a name, or as a hash of names to
26
+ # conditions, which may be a subclass such as HashWithIndifferentAccess.
27
+ #: (Array[untyped], String?) -> bool
28
+ def self.named?(entries, name)
29
+ entries.any? { |entry| entry.is_a?(Hash) ? entry.key?(name) : entry == name }
30
+ end
31
+ private_class_method :named?
32
+ end
33
+ end
@@ -44,11 +44,7 @@ module PaperTrailDiff
44
44
  end
45
45
 
46
46
  #: () -> RootVersionPlan
47
- def empty
48
- versions = [] #: Array[untyped]
49
- steps = [] #: Array[[untyped, untyped]]
50
- new(versions: versions, steps: steps)
51
- end
47
+ def empty = closing_on(nil)
52
48
 
53
49
  # No root version to report or replay: only descendants moved, and the
54
50
  # live record is the root's state throughout.
@@ -82,13 +78,12 @@ module PaperTrailDiff
82
78
  end
83
79
 
84
80
  #: () -> RootVersionPlan
85
- def closing_on_destroy
86
- self.class.new(
87
- versions: versions, steps: steps, context_version: context_version,
88
- reconstruction_versions: reconstruction_versions, mutations: mutations,
89
- closing_record: closing_record, closes_on_destroy: true
90
- )
91
- end
81
+ def closing_on_destroy = copy(closes_on_destroy: true)
82
+
83
+ # The same plan reporting only `selected` as mutations, of the versions it
84
+ # holds.
85
+ #: (Array[untyped]) -> RootVersionPlan
86
+ def reporting(selected) = copy(mutations: selected)
92
87
 
93
88
  # What the range's final state is read from, which is the live record when
94
89
  # the window closes on current state and the last version otherwise.
@@ -99,19 +94,28 @@ module PaperTrailDiff
99
94
 
100
95
  #: (untyped) -> bool
101
96
  def mutation?(version)
102
- @mutation_keys.include?(key(version))
97
+ @mutation_keys.include?(Support.row_key(version))
103
98
  end
104
99
 
105
100
  private
106
101
 
107
102
  # @rbs @mutation_keys: Set[Array[untyped]]
108
103
 
104
+ #: (**untyped) -> RootVersionPlan
105
+ def copy(**changes)
106
+ self.class.new(
107
+ versions: versions, steps: steps, context_version: context_version,
108
+ reconstruction_versions: reconstruction_versions, mutations: mutations,
109
+ closing_record: closing_record, closes_on_destroy: closes_on_destroy, **changes
110
+ )
111
+ end
112
+
109
113
  #: () -> Array[untyped]
110
114
  def default_mutations
111
115
  return @versions unless @context_version
112
116
 
113
- context = key(@context_version)
114
- @versions.reject { |version| key(version) == context }
117
+ context = Support.row_key(@context_version)
118
+ @versions.reject { |version| Support.row_key(version) == context }
115
119
  end
116
120
 
117
121
  # A Set only makes the lookup in `mutation?` fast; an Array would answer the
@@ -119,13 +123,7 @@ module PaperTrailDiff
119
123
  # mutant:disable
120
124
  #: (Array[untyped]) -> Set[Array[untyped]]
121
125
  def key_set(versions)
122
- Set.new(versions.map { |version| key(version) })
123
- end
124
-
125
- # By class name, so a version still matches after its class is reloaded.
126
- #: (untyped) -> Array[untyped]
127
- def key(version)
128
- [version.class.name, version.id]
126
+ Set.new(versions.map { |version| Support.row_key(version) })
129
127
  end
130
128
  end
131
129
  end
@@ -9,7 +9,9 @@ module PaperTrailDiff
9
9
  # a filter must never remove it.
10
10
  #
11
11
  # Both the single-record and the batched selectors resolve this here, because
12
- # the rule is subtle enough that two copies of it would drift apart.
12
+ # the rule is subtle enough that two copies of it would drift apart. Their
13
+ # versions are put in order here too, which refuses a sequence that cannot
14
+ # be ordered (see Support.chronological_sort) whichever selector read it.
13
15
  class RootVersionSelection
14
16
  # An error is a specification, so it names the way out as well as the wall.
15
17
  # A window ending at the present can never gain a later version, which makes
@@ -20,17 +22,23 @@ module PaperTrailDiff
20
22
  'final change, and there is no current record to end at: narrow ' \
21
23
  'the window to end before the last recorded version'
22
24
 
23
- #: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
25
+ # `selected` is what a filter keeps of `in_range`; one that keeps every
26
+ # version is no filter. Activity on associations reports the changes a
27
+ # filter keeps on them wherever they fall in the range, so a `whole` plan
28
+ # replays every root version there, as one without a filter does, and the
29
+ # filter names only which of them are the root's own mutations.
30
+ #: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?live_endpoint: untyped, ?whole: bool) -> void
24
31
  def initialize( # rubocop:disable Metrics/ParameterLists
25
- in_range:, selected:, after_range:, windowed:, context_required: false, filtered: false,
26
- live_endpoint: nil
32
+ in_range:, selected:, after_range:, windowed:, context_required: false, live_endpoint: nil,
33
+ whole: false
27
34
  )
28
- @in_range = in_range
29
- @selected = selected
35
+ @in_range = Support.chronological_sort(in_range)
36
+ @reported = Support.chronological_sort(selected)
37
+ @selected = whole ? @in_range : @reported
30
38
  @after_range = after_range
31
39
  @windowed = windowed
32
40
  @context_required = context_required
33
- @filtered = filtered
41
+ @filtered = @selected.length < @in_range.length
34
42
  @live_endpoint = live_endpoint
35
43
  end
36
44
 
@@ -40,12 +48,14 @@ module PaperTrailDiff
40
48
 
41
49
  closing = revealing_version || @live_endpoint
42
50
  plan = @filtered ? filtered_plan(closing) : contiguous_plan(closing)
43
- closes_on_destroy?(closing) ? plan.closing_on_destroy : plan
51
+ plan = plan.closing_on_destroy if closes_on_destroy?(closing)
52
+ plan.reporting(@reported)
44
53
  end
45
54
 
46
55
  private
47
56
 
48
57
  # @rbs @in_range: Array[untyped]
58
+ # @rbs @reported: Array[untyped]
49
59
  # @rbs @selected: Array[untyped]
50
60
  # @rbs @after_range: untyped
51
61
  # @rbs @windowed: bool
@@ -96,17 +106,15 @@ module PaperTrailDiff
96
106
  filtered_plan_for(steps, revealing)
97
107
  end
98
108
 
109
+ # The steps run in order, and so do the versions they pass.
99
110
  #: (Array[[untyped, untyped]], untyped) -> RootVersionPlan
100
111
  def filtered_plan_for(steps, revealing)
101
112
  live = revealing if Endpoint.record?(revealing)
102
- versions = chronological(
103
- (steps.flatten(1) + closing_versions).reject { |entry| Endpoint.record?(entry) }
104
- )
113
+ versions = (steps.flatten + closing_versions).reject { |entry| Endpoint.record?(entry) }.uniq
105
114
  RootVersionPlan.new(
106
115
  versions: versions, steps: steps,
107
116
  context_version: (revealing unless live),
108
- reconstruction_versions: spanned(versions),
109
- mutations: @selected, closing_record: live
117
+ reconstruction_versions: spanned(versions), closing_record: live
110
118
  )
111
119
  end
112
120
 
@@ -119,30 +127,32 @@ module PaperTrailDiff
119
127
  terminal_destroy? ? [@selected.last] : []
120
128
  end
121
129
 
122
- # Everything the span passes through, filtered out or not. A replay that
123
- # skipped the excluded versions would carry a stale state into the next
124
- # reported step, so the two selected mutations either side of a gap would
125
- # disagree about what the record looked like between them.
126
- #: (Array[untyped]) -> Array[untyped]
130
+ # Everything the span passes through, filtered out or not, through the
131
+ # version that reveals the last selected mutation, which can lie after the
132
+ # range. A replay that skipped the excluded versions would carry a stale
133
+ # state into the next reported step, so the two selected mutations either
134
+ # side of a gap would disagree about what the record looked like between
135
+ # them. One that stopped before the revealing version would read what the
136
+ # last one produced from history that ends before it. Only the version
137
+ # that reveals the last can lie outside the range, and it comes after it.
138
+ # With no versions there is no span, and a plan replays its versions.
139
+ #: (Array[untyped]) -> Array[untyped]?
127
140
  def spanned(versions)
141
+ return if versions.empty?
142
+
128
143
  first = versions.first
129
144
  last = versions.last
130
- return versions unless first && last
131
-
132
- @in_range.select do |candidate|
145
+ (@in_range.select do |candidate|
133
146
  !Support.compare_versions(first, candidate).positive? &&
134
147
  !Support.compare_versions(candidate, last).positive?
135
- end
136
- end
137
-
138
- #: (Array[untyped]) -> Array[untyped]
139
- def chronological(versions)
140
- Support.chronological_sort(versions.uniq { |version| [version.class.name, version.id] })
148
+ end + versions).uniq
141
149
  end
142
150
 
151
+ # The versions in range are in order, so the first one after a version is
152
+ # found by a search rather than by passing every version before it.
143
153
  #: (untyped) -> untyped
144
154
  def immediate_successor(version)
145
- @in_range.find { |candidate| Support.compare_versions(version, candidate).negative? }
155
+ @in_range.bsearch { |candidate| Support.compare_versions(version, candidate).negative? }
146
156
  end
147
157
 
148
158
  # A version left out by a filter is still the state the last selected change
@@ -166,7 +176,7 @@ module PaperTrailDiff
166
176
  # nothing can follow it, so demanding one would reject the range forever.
167
177
  #: () -> bool
168
178
  def terminal_destroy?
169
- @selected.last&.event.to_s == 'destroy'
179
+ @selected.last.event == 'destroy'
170
180
  end
171
181
  end
172
182
  end