paper_trail_diff 0.13.1 → 0.15.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 (181) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +630 -0
  3. data/QUICKSTART.md +30 -10
  4. data/README.md +91 -13
  5. data/docs/architecture.md +62 -18
  6. data/docs/performance.md +116 -298
  7. data/docs/reference.md +554 -102
  8. data/docs/testing.md +93 -14
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  14. data/lib/paper_trail_diff/activity_event.rb +41 -10
  15. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  16. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  17. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  18. data/lib/paper_trail_diff/activity_history.rb +34 -9
  19. data/lib/paper_trail_diff/activity_range.rb +32 -5
  20. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  22. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  23. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
  25. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  27. data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
  28. data/lib/paper_trail_diff/activity_view.rb +69 -0
  29. data/lib/paper_trail_diff/analysis.rb +13 -1
  30. data/lib/paper_trail_diff/analysis_batch.rb +24 -30
  31. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  32. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  33. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  34. data/lib/paper_trail_diff/association_discovery.rb +14 -11
  35. data/lib/paper_trail_diff/association_key.rb +56 -0
  36. data/lib/paper_trail_diff/association_traversal.rb +180 -47
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  38. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  39. data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
  40. data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
  41. data/lib/paper_trail_diff/change_row.rb +133 -0
  42. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  43. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  44. data/lib/paper_trail_diff/configuration.rb +35 -12
  45. data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
  46. data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
  47. data/lib/paper_trail_diff/deprecation.rb +61 -0
  48. data/lib/paper_trail_diff/diagnostics.rb +105 -102
  49. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  50. data/lib/paper_trail_diff/endpoint.rb +26 -3
  51. data/lib/paper_trail_diff/errors.rb +5 -2
  52. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  53. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  54. data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
  55. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
  57. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
  58. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  59. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  60. data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
  61. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  63. data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
  64. data/lib/paper_trail_diff/prepared_history.rb +70 -53
  65. data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
  66. data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
  67. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  68. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  69. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  70. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  71. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  72. data/lib/paper_trail_diff/scope_condition.rb +386 -0
  73. data/lib/paper_trail_diff/scope_ranking.rb +206 -0
  74. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  75. data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
  76. data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
  77. data/lib/paper_trail_diff/snapshot.rb +16 -1
  78. data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
  79. data/lib/paper_trail_diff/support.rb +38 -6
  80. data/lib/paper_trail_diff/time_range.rb +37 -18
  81. data/lib/paper_trail_diff/time_version_range.rb +5 -5
  82. data/lib/paper_trail_diff/timeline_builder.rb +7 -7
  83. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  84. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  85. data/lib/paper_trail_diff/transaction_cut.rb +181 -0
  86. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  87. data/lib/paper_trail_diff/version.rb +1 -1
  88. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  89. data/lib/paper_trail_diff/version_boundary.rb +37 -8
  90. data/lib/paper_trail_diff/version_query.rb +34 -10
  91. data/lib/paper_trail_diff/version_range.rb +8 -15
  92. data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
  93. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
  94. data/lib/paper_trail_diff/version_table.rb +60 -0
  95. data/lib/paper_trail_diff.rb +126 -55
  96. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  97. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  98. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  99. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  100. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  101. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  102. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  103. data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
  104. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  105. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  106. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  107. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  108. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
  109. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  110. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
  111. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  112. data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
  113. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  114. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  115. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  116. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  117. data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
  118. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  119. data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
  120. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  121. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
  122. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
  123. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  124. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  125. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  126. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  127. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
  128. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
  129. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  130. data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
  131. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  132. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  133. data/sig/generated/paper_trail_diff/errors.rbs +5 -2
  134. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  135. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  136. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  137. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  138. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
  139. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
  140. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  141. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
  142. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  143. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  144. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  145. data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
  146. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  147. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
  148. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  149. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  150. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  151. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  152. data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
  153. data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
  154. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  155. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
  156. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
  157. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  158. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
  159. data/sig/generated/paper_trail_diff/support.rbs +20 -2
  160. data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
  161. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  162. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  163. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  164. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  165. data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
  166. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  167. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  168. data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
  169. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  170. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  171. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
  172. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
  173. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  174. data/sig/generated/paper_trail_diff.rbs +47 -25
  175. metadata +62 -10
  176. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  177. data/lib/paper_trail_diff/batch_safety.rb +0 -55
  178. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
  179. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  180. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
  181. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -0,0 +1,68 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # PT-AT records HABTM members under a transaction id and the association's
6
+ # name, with nothing naming the record they belong to. When more than one
7
+ # record that can own that name saved a version in the transaction, their
8
+ # members are mixed together and none of them can be read back.
9
+ class HabtmTransactionOwners
10
+ #: (untyped, untyped) -> void
11
+ def initialize(owner_class, reflection)
12
+ @versions = owner_class.paper_trail.version_class
13
+ @associations = owner_class.paper_trail.version_association_class
14
+ @name = reflection.name.to_s
15
+ @owner_types = {} #: Hash[String, bool]
16
+ end
17
+
18
+ # The given transactions (one id or several) in which more than one
19
+ # possible owner saved a version, as strings.
20
+ #: (untyped) -> Array[String]
21
+ def shared(transaction_ids)
22
+ items = @versions.where(transaction_id: transaction_ids).distinct
23
+ .pluck(:transaction_id, :item_type, :item_id)
24
+ owners = items.select { |_, type, _| owner_type?(type) }
25
+ owners.group_by { |transaction_id, _, _| transaction_id.to_s }
26
+ .filter_map { |transaction_id, rows| transaction_id if rows.size > 1 }
27
+ end
28
+
29
+ # Members recorded in a shared transaction cannot be told apart. With no
30
+ # members recorded, every owner had none, so that reads correctly.
31
+ #: (untyped) -> bool
32
+ def ambiguous?(transaction_id)
33
+ shared(transaction_id).any? &&
34
+ @associations.exists?(version_id: transaction_id, foreign_key_name: @name)
35
+ end
36
+
37
+ #: (untyped) -> void
38
+ def ensure_single_owner!(transaction_id)
39
+ return unless ambiguous?(transaction_id)
40
+
41
+ message = "HABTM history is ambiguous for #{@name} at transaction #{transaction_id}: " \
42
+ "more than one record with a #{@name} association saved a version in it, " \
43
+ 'and PT-AT does not record which members belong to which record'
44
+ raise IncompleteAssociationHistoryError, message
45
+ end
46
+
47
+ private
48
+
49
+ # @rbs @versions: untyped
50
+ # @rbs @associations: untyped
51
+ # @rbs @name: String
52
+ # @rbs @owner_types: Hash[String, bool]
53
+
54
+ # Versions name the base class, so a HABTM declared on a subclass counts.
55
+ # A type that names no model may have recorded members when it existed.
56
+ #: (String) -> bool
57
+ def owner_type?(type)
58
+ @owner_types.fetch(type) do
59
+ model_class = AssociationTraversal.named_class(type)
60
+ @owner_types[type] =
61
+ !model_class.respond_to?(:reflect_on_association) ||
62
+ [model_class, *model_class.descendants].any? do |candidate|
63
+ candidate.reflect_on_association(@name)&.macro == :has_and_belongs_to_many
64
+ end
65
+ end
66
+ end
67
+ end
68
+ end
@@ -6,10 +6,8 @@ module PaperTrailDiff
6
6
  class HistoricalAssociationReifier
7
7
  #: (untyped, ?habtm_version: untyped) -> void
8
8
  def initialize(version, habtm_version: version)
9
- @transaction_id = version.transaction_id if version.respond_to?(:transaction_id)
10
- if habtm_version.respond_to?(:transaction_id)
11
- @habtm_transaction_id = habtm_version.transaction_id
12
- end
9
+ @transaction_id = VersionBoundary.transaction_id(version)
10
+ @habtm_transaction_id = VersionBoundary.transaction_id(habtm_version)
13
11
  @version_at = version.created_at
14
12
  # Keyed on record identity rather than `object_id`, which Ruby may reuse
15
13
  # once an earlier record in the same pass has been collected.
@@ -37,7 +35,7 @@ module PaperTrailDiff
37
35
  reified[reflection.name] = true
38
36
  case reflection.macro
39
37
  when :belongs_to
40
- reifier(:BelongsTo).reify(reflection, record, options, @transaction_id)
38
+ reify_belongs_to(record, reflection)
41
39
  when :has_one
42
40
  reifier(:HasOne).reify(reflection, record, options, @transaction_id)
43
41
  when :has_many
@@ -47,6 +45,26 @@ module PaperTrailDiff
47
45
  end
48
46
  end
49
47
 
48
+ #: (untyped, untyped) -> void
49
+ def reify_belongs_to(record, reflection)
50
+ ensure_versioned_target!(record, reflection) if reflection.polymorphic?
51
+ reifier(:BelongsTo).reify(reflection, record, options, @transaction_id)
52
+ end
53
+
54
+ # A polymorphic target's class is known only from the record's type
55
+ # column, so TraversalPreparer cannot check it is versioned up front.
56
+ #: (untyped, untyped) -> void
57
+ def ensure_versioned_target!(record, reflection)
58
+ model_class = AssociationTraversal.belongs_to_target(reflection, record)
59
+ return if model_class.nil? || Support.versioned?(model_class)
60
+
61
+ raise UnversionedAssociationError,
62
+ "association #{record.class.name}##{reflection.name} cannot be compared " \
63
+ "historically: it points at #{model_class.name}, which is not versioned. Add " \
64
+ "`has_paper_trail` to #{model_class.name}, or mirror the fields you need onto a " \
65
+ 'model that has it.'
66
+ end
67
+
50
68
  #: (untyped, untyped) -> void
51
69
  def reify_has_many(record, reflection)
52
70
  if reflection.options[:through]
@@ -70,7 +88,7 @@ module PaperTrailDiff
70
88
  #: (untyped, untyped) -> void
71
89
  def reify_through(record, reflection)
72
90
  source = reflection.source_reflection
73
- if source.belongs_to?
91
+ if pt_at_source?(reflection)
74
92
  reifier(:HasManyThrough).reify(reflection, record, options, @transaction_id)
75
93
  return
76
94
  end
@@ -81,9 +99,17 @@ module PaperTrailDiff
81
99
  association.loaded!
82
100
  end
83
101
 
102
+ # PT-AT's belongs_to source ignores `source_type:` and reads targets by id
103
+ # alone, so a typed through walks its join records instead.
104
+ #: (untyped) -> bool
105
+ def pt_at_source?(reflection)
106
+ reflection.source_reflection.belongs_to? && !reflection.options[:source_type]
107
+ end
108
+
84
109
  #: (untyped, untyped, untyped) -> Array[untyped]
85
110
  def through_members(record, reflection, source)
86
111
  joins = Array(record.public_send(reflection.through_reflection.name)) #: Array[untyped]
112
+ joins = joins.select { |join| AssociationTraversal.source_type_join?(reflection, join) }
87
113
  joins.flat_map do |join|
88
114
  reify_association(join, source)
89
115
  Array(join.public_send(source.name))
@@ -96,6 +122,8 @@ module PaperTrailDiff
96
122
  message = 'HABTM reconstruction requires a transaction-backed endpoint version'
97
123
  raise IncompleteAssociationHistoryError, message
98
124
  end
125
+ HabtmTransactionOwners.new(record.class, reflection)
126
+ .ensure_single_owner!(@habtm_transaction_id)
99
127
 
100
128
  paper_trail = Object.const_get(:PaperTrail) #: untyped
101
129
  target_versioned = paper_trail.request.enabled_for_model?(reflection.klass)
@@ -24,8 +24,10 @@ module PaperTrailDiff
24
24
  @state_loader = PreparedVersionStateLoader.new
25
25
  end
26
26
 
27
- #: (Array[String]) -> Array[String]
28
- def call(candidates)
27
+ # More matches than the limit raise, unless the caller does not count
28
+ # them: candidates it only lists, such as deleted roots.
29
+ #: (Array[String], ?counted: bool) -> Array[String]
30
+ def call(candidates, counted: true)
29
31
  matched = [] #: Array[String]
30
32
  candidates.each_slice(CANDIDATE_BATCH) do |slice|
31
33
  versions = candidate_versions(slice)
@@ -34,7 +36,7 @@ module PaperTrailDiff
34
36
  next unless held?(versions.fetch(id, []), closing[id])
35
37
 
36
38
  matched << id
37
- reject_root_limit! if matched.length > @limit
39
+ reject_root_limit! if counted && matched.length > @limit
38
40
  end
39
41
  end
40
42
  matched
@@ -64,7 +66,17 @@ module PaperTrailDiff
64
66
  "unknown historical attributes: #{unknown.join(', ')}"
65
67
  end
66
68
 
67
- Support.immutable_copy(attributes)
69
+ attributes.to_h { |name, value| [name, cast(name, value)] }
70
+ end
71
+
72
+ # Expected and recorded values compare as the attribute casts them, as
73
+ # `where` reads its values: an enum's symbol names its stored value, and a
74
+ # `json` or `jsonb` version column, which PaperTrail does not cast, holds
75
+ # dates and times as strings. Casting also copies a mutable value, so the
76
+ # filter keeps its own.
77
+ #: (String, untyped) -> untyped
78
+ def cast(name, value)
79
+ @model.type_for_attribute(name).cast(value)
68
80
  end
69
81
 
70
82
  #: (untyped) -> Integer
@@ -76,8 +88,7 @@ module PaperTrailDiff
76
88
 
77
89
  #: (Array[String]) -> Hash[String, Array[untyped]]
78
90
  def candidate_versions(ids)
79
- relation = @model.paper_trail.version_class.where(item_type: @model.base_class.name,
80
- item_id: ids)
91
+ relation = VersionQuery.for_items(@model, ids)
81
92
  range = @time_range
82
93
  relation = range.scope(relation) if range
83
94
  # One past the remaining budget is enough to know it was exceeded.
@@ -107,9 +118,7 @@ module PaperTrailDiff
107
118
  range = @time_range
108
119
  return {} unless range
109
120
 
110
- relation = @model.paper_trail.version_class.where(item_type: @model.base_class.name,
111
- item_id: ids)
112
- trailing = range.first_trailing_versions(relation)
121
+ trailing = range.first_trailing_versions(VersionQuery.for_items(@model, ids))
113
122
  account_versions!(trailing.length)
114
123
  trailing
115
124
  end
@@ -162,7 +171,7 @@ module PaperTrailDiff
162
171
  "historical_filter: #{name} was not recorded in version #{version.id}"
163
172
  end
164
173
 
165
- state.attributes.fetch(name) == expected
174
+ cast(name, state.attributes.fetch(name)) == expected
166
175
  end
167
176
  end
168
177
 
@@ -2,7 +2,10 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Reconstructs and caches immutable historical snapshots for one adapter configuration.
5
+ # Reconstructs and caches immutable historical snapshots for one adapter
6
+ # configuration. It keeps the histories batches prepare, by root version;
7
+ # one prepared for a single root goes back to the caller, who passes it to
8
+ # every read for that root.
6
9
  class HistoricalSnapshotStore
7
10
  #: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
8
11
  def initialize(tree:, traversal:, normalizer:, preparer:)
@@ -13,11 +16,11 @@ module PaperTrailDiff
13
16
  @prepared_snapshotter = PreparedSnapshotBuilder.new(traversal)
14
17
  @live_graph_collector = LiveGraphCollector.new(tree: tree, traversal: traversal)
15
18
  @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
16
- @prepared_history = nil #: PreparedHistory?
17
19
  @prepared_histories = {} #: Hash[Array[untyped], PreparedHistory]
20
+ @live_roots = {} #: Hash[identity, untyped]
18
21
  end
19
22
 
20
- #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
23
+ #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory?
21
24
  def prepare(
22
25
  record,
23
26
  root_versions,
@@ -28,18 +31,11 @@ module PaperTrailDiff
28
31
 
29
32
  # A batched preparation already covers these roots.
30
33
  batched = root_versions.find { |version| @prepared_histories.key?(context_key(version)) }
31
- if batched
32
- @prepared_history = @prepared_histories.fetch(context_key(batched))
33
- return
34
- end
34
+ return @prepared_histories.fetch(context_key(batched)) if batched
35
35
 
36
- @prepared_history = PreparedHistoryLoader.new(
37
- record,
38
- root_versions: root_versions,
39
- start_at: start_at,
40
- end_at: end_at,
41
- tree: @tree,
42
- traversal: @traversal
36
+ PreparedHistoryLoader.new(
37
+ record, root_ids: [record.id], root_versions: root_versions, start_at: start_at,
38
+ end_at: end_at, tree: @tree, traversal: @traversal, live_records: []
43
39
  ).call
44
40
  end
45
41
 
@@ -50,10 +46,14 @@ module PaperTrailDiff
50
46
  Instrumentation.instrument('prepare_history', batch_payload(records, root_versions)) do
51
47
  register_batch(records, root_versions, start_at: start_at, end_at: end_at)
52
48
  end
49
+ # A batch passes its roots as it just loaded them, so the current state
50
+ # they close on is read from them rather than once more per root.
51
+ records.each { |record| @live_roots[Endpoint.identity(record)] = record }
53
52
  end
54
53
 
55
- # Missing roots have no live graph to collect. Reading their associations
56
- # here would issue a query per root and seed nonexistent rows as live state.
54
+ # Missing roots, and roots compared only between versions, have no live
55
+ # graph to collect. Reading their associations here would issue a query
56
+ # per root and seed nonexistent rows as live state.
57
57
  #: (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
58
58
  def prepare_deleted_batch(records, root_versions, start_at: nil, end_at: nil)
59
59
  return if @tree.empty? || records.empty? || root_versions.empty?
@@ -61,50 +61,41 @@ module PaperTrailDiff
61
61
  register_batch(records, root_versions, live_records: [], start_at: start_at, end_at: end_at)
62
62
  end
63
63
 
64
- #: (untyped, untyped) -> RecordSnapshot?
65
- def call(root_endpoint, context_endpoint)
64
+ # `history` is the one `prepare` returned for this root, if any.
65
+ #: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
66
+ def call(root_endpoint, context_endpoint, history: nil)
66
67
  key = snapshot_key(root_endpoint, context_endpoint)
67
68
  return @snapshots[key] if @snapshots.key?(key)
68
69
 
69
- @snapshots[key] = uncached(root_endpoint, context_endpoint)
70
+ @snapshots[key] = uncached(root_endpoint, context_endpoint, history: history)
70
71
  end
71
72
 
72
- #: (untyped, untyped) -> RecordSnapshot?
73
- def uncached(root_endpoint, context_endpoint)
74
- custom(
75
- root_endpoint,
76
- context_endpoint,
77
- tree: @tree,
78
- normalizer: @normalizer
79
- )
73
+ #: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
74
+ def uncached(root_endpoint, context_endpoint, history: nil)
75
+ custom(root_endpoint, context_endpoint, tree: @tree, normalizer: @normalizer,
76
+ history: history)
80
77
  end
81
78
 
82
- #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
83
- def custom(root_endpoint, context_endpoint, tree:, normalizer:)
79
+ #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, ?history: PreparedHistory?) -> RecordSnapshot?
80
+ def custom(root_endpoint, context_endpoint, tree:, normalizer:, history: nil)
81
+ history = history_for(context_endpoint, history)
84
82
  if Endpoint.version?(root_endpoint)
85
83
  return snapshot_from_version(
86
- root_endpoint,
87
- context_endpoint,
88
- tree: tree,
89
- normalizer: normalizer
84
+ root_endpoint, context_endpoint, tree: tree, normalizer: normalizer, history: history
90
85
  )
91
86
  end
92
87
 
93
- snapshot_from_live_root(
94
- root_endpoint,
95
- context_endpoint,
96
- tree: tree,
97
- normalizer: normalizer
98
- )
88
+ snapshot_from_live_root(root_endpoint, context_endpoint, tree: tree, normalizer: normalizer,
89
+ history: history)
99
90
  end
100
91
 
101
- #: (untyped, habtm_version: untyped) -> untyped
102
- def association_reader(context_version, habtm_version:)
92
+ #: (untyped, habtm_version: untyped, ?history: PreparedHistory?) -> untyped
93
+ def association_reader(context_version, habtm_version:, history: nil)
103
94
  fallback = HistoricalAssociationReifier.new(
104
95
  context_version,
105
96
  habtm_version: habtm_version
106
97
  )
107
- history = @prepared_histories[context_key(context_version)] || @prepared_history
98
+ history = history_for(context_version, history)
108
99
  return fallback unless history
109
100
 
110
101
  PreparedAssociationReifier.new(
@@ -115,25 +106,6 @@ module PaperTrailDiff
115
106
  )
116
107
  end
117
108
 
118
- #: () -> PreparedActivityIndex?
119
- def activity_index
120
- @prepared_history&.activity_index
121
- end
122
-
123
- #: (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
124
- def record_transition(version)
125
- history = @prepared_history
126
- return unless history
127
-
128
- history.record_transition(Endpoint.model_class(version), version.item_id, version)
129
- end
130
-
131
- #: (untyped, ?direct: bool) -> [bool, untyped]
132
- def record_after(version, direct: false)
133
- @prepared_history&.record_after(Endpoint.model_class(version), version.item_id, version,
134
- direct: direct) || [false, nil]
135
- end
136
-
137
109
  private
138
110
 
139
111
  # @rbs @tree: AssociationTree
@@ -143,8 +115,14 @@ module PaperTrailDiff
143
115
  # @rbs @prepared_snapshotter: PreparedSnapshotBuilder
144
116
  # @rbs @live_graph_collector: LiveGraphCollector
145
117
  # @rbs @snapshots: Hash[Array[untyped], RecordSnapshot?]
146
- # @rbs @prepared_history: PreparedHistory?
147
118
  # @rbs @prepared_histories: Hash[Array[untyped], PreparedHistory]
119
+ # @rbs @live_roots: Hash[identity, untyped]
120
+
121
+ # A batch's history for the version wins over the one a caller passes.
122
+ #: (untyped, PreparedHistory?) -> PreparedHistory?
123
+ def history_for(context_endpoint, history)
124
+ @prepared_histories[context_key(context_endpoint)] || history
125
+ end
148
126
 
149
127
  #: (untyped) -> Array[untyped]
150
128
  def context_key(endpoint)
@@ -173,34 +151,43 @@ module PaperTrailDiff
173
151
  root_versions.each { |version| @prepared_histories[context_key(version)] = history }
174
152
  end
175
153
 
176
- #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
177
- def snapshot_from_version(root_version, context_version, tree:, normalizer:)
178
- model_class = Endpoint.model_class(root_version)
154
+ #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
155
+ def snapshot_from_version(root_version, context_version, tree:, normalizer:, history:)
156
+ model_class = RecordedClass.for(root_version)
179
157
  @preparer.call(model_class, historical: true)
180
158
  @traversal.ensure_habtm_history!(model_class, root_version)
181
159
  handled, snapshot = @prepared_snapshotter.call(
182
- root_version, context_version, tree: tree, normalizer: normalizer,
183
- history: @prepared_histories[context_key(context_version)] ||
184
- @prepared_history
160
+ root_version, context_version, tree: tree, normalizer: normalizer, history: history
185
161
  )
186
162
  return snapshot if handled
187
163
 
188
164
  record = root_version.reify(dup: true)
189
165
  normalize(record, context_version, tree: tree, normalizer: normalizer,
190
- habtm_version: root_version)
166
+ habtm_version: root_version, history: history)
191
167
  end
192
168
 
193
- #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
194
- def snapshot_from_live_root(root_record, context_version, tree:, normalizer:)
195
- record = Endpoint.reload_record(root_record)
169
+ #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
170
+ def snapshot_from_live_root(root_record, context_version, tree:, normalizer:, history:)
171
+ record = live_root(root_record)
196
172
  @preparer.call(record.class, historical: true)
197
173
  normalize(record, context_version, tree: tree, normalizer: normalizer,
198
- habtm_version: context_version)
174
+ habtm_version: context_version, history: history)
175
+ end
176
+
177
+ # Rebuilding a version's associations writes them onto the record, so each
178
+ # snapshot gets its own copy of a batch's loaded row, built from the row's
179
+ # stored values without a query.
180
+ #: (untyped) -> untyped
181
+ def live_root(root_record)
182
+ loaded = @live_roots[Endpoint.identity(root_record)]
183
+ return Endpoint.reload_record(root_record) unless loaded
184
+
185
+ loaded.class.instantiate(loaded.attributes_before_type_cast)
199
186
  end
200
187
 
201
- #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped) -> RecordSnapshot?
202
- def normalize(record, context_version, tree:, normalizer:, habtm_version:)
203
- reifier = association_reader(context_version, habtm_version: habtm_version)
188
+ #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped, history: PreparedHistory?) -> RecordSnapshot?
189
+ def normalize(record, context_version, tree:, normalizer:, habtm_version:, history:) # rubocop:disable Metrics/ParameterLists
190
+ reifier = association_reader(context_version, habtm_version: habtm_version, history: history)
204
191
  reflections = [] #: Array[untyped]
205
192
  reflections = @traversal.reflections_for(record.class, tree, path: '') if record
206
193
  reifier.reify(record, reflections) if record && !reflections.empty?
@@ -44,9 +44,9 @@ module PaperTrailDiff
44
44
 
45
45
  #: (untyped, Array[untyped], AssociationTree) -> void
46
46
  def preload_model_tree(model_class, records, tree)
47
- batch, individual = selected_reflections(model_class, tree).partition do |reflection, _|
48
- batch_safe?(records.fetch(0), reflection)
49
- end
47
+ reflections = selected_reflections(model_class, tree)
48
+ resolve_polymorphic_targets(records, reflections)
49
+ batch, individual = reflections.partition { |reflection, _| BatchPreload.safe?(reflection) }
50
50
  preload_batch(records, batch.map { |reflection, _| reflection.name })
51
51
  preload_subtrees(records, batch, individually: false)
52
52
  preload_subtrees(records, individual, individually: true)
@@ -62,6 +62,15 @@ module PaperTrailDiff
62
62
  end
63
63
  end
64
64
 
65
+ # Active Record raises a bare NameError for a type that names no class, so
66
+ # each type is resolved first to raise one that names the record.
67
+ #: (Array[untyped], Array[[untyped, AssociationTree]]) -> void
68
+ def resolve_polymorphic_targets(records, reflections)
69
+ reflections.map(&:first).select(&:polymorphic?).each do |reflection|
70
+ records.each { |record| AssociationTraversal.belongs_to_target(reflection, record) }
71
+ end
72
+ end
73
+
65
74
  #: (Array[untyped], Array[[untyped, AssociationTree]], individually: bool) -> void
66
75
  def preload_subtrees(records, reflections, individually:)
67
76
  reflections.each do |reflection, subtree|
@@ -90,16 +99,6 @@ module PaperTrailDiff
90
99
  active_record.const_get(:Associations).const_get(:Preloader)
91
100
  end
92
101
 
93
- #: (untyped, untyped) -> bool
94
- def batch_safe?(record, reflection)
95
- scope = reflection.scope
96
- return false if scope && !scope.arity.zero?
97
- return true unless reflection.collection?
98
-
99
- relation = record.association(reflection.name).scope
100
- relation.limit_value.nil? && relation.offset_value.nil?
101
- end
102
-
103
102
  #: (Array[untyped], untyped) -> Array[untyped]
104
103
  def load_individually(records, reflection)
105
104
  unique_records(records.flat_map do |record|
@@ -36,7 +36,7 @@ module PaperTrailDiff
36
36
  subtree = tree.child(reflection.name)
37
37
  next unless subtree
38
38
 
39
- child_path = Support.association_path(path, reflection.name.to_s)
39
+ child_path = Support.association_path(path, reflection.name)
40
40
  collect(children_for(records, reflection), subtree, path: child_path, into: into)
41
41
  end
42
42
  end
@@ -52,13 +52,17 @@ module PaperTrailDiff
52
52
  # Returns the changed paths, or an empty hash when the pair is not two
53
53
  # structures this can look inside. An empty result therefore means "nothing
54
54
  # to report at this depth", and the caller still has the whole-value change.
55
+ # Two arrays at the top are one membership change, at the empty path.
55
56
  #: () -> nested_changes
56
57
  def call
57
- from_structure, to_structure = structures
58
+ from, to = structures
58
59
  changes = {} #: nested_changes
59
- return changes.freeze unless from_structure && to_structure
60
-
61
- walk(from_structure, to_structure, [], changes)
60
+ if from.is_a?(Hash) && to.is_a?(Hash)
61
+ walk(from, to, [], changes)
62
+ elsif from.is_a?(Array) && to.is_a?(Array)
63
+ whole = [] #: Array[String]
64
+ changes[whole.freeze] = change_for(from, to) if from != to
65
+ end
62
66
  changes.freeze
63
67
  end
64
68
 
@@ -67,26 +71,23 @@ module PaperTrailDiff
67
71
  # @rbs @from_value: untyped
68
72
  # @rbs @to_value: untyped
69
73
 
70
- # Both sides have to be readable as a Hash for a nested answer to mean
71
- # anything. A column that held text on one side and JSON on the other
72
- # changed wholesale, and saying so is the accurate report.
73
- #: () -> [Hash[untyped, untyped]?, Hash[untyped, untyped]?]
74
+ # Both sides have to be readable as the same kind of structure for a
75
+ # nested answer to mean anything. A column that held text on one side and
76
+ # JSON on the other changed wholesale, and saying so is the accurate report.
77
+ #: () -> [untyped, untyped]
74
78
  def structures
75
79
  [structure(@from_value), structure(@to_value)]
76
80
  end
77
81
 
78
- #: (untyped) -> Hash[untyped, untyped]?
82
+ # A string is read as JSON; anything else, or JSON that is neither an
83
+ # object nor an array, is left for #call to decline.
84
+ #: (untyped) -> untyped
79
85
  def structure(value)
80
- return value if value.is_a?(Hash)
81
- return unless value.is_a?(String)
86
+ return value unless value.is_a?(String)
82
87
 
83
- parsed = begin
84
- JSON.parse(value)
85
- rescue JSON::ParserError
86
- nil
87
- end
88
- # JSON parses objects into plain Hashes, never a subclass.
89
- parsed if parsed.instance_of?(Hash)
88
+ JSON.parse(value)
89
+ rescue JSON::ParserError
90
+ nil
90
91
  end
91
92
 
92
93
  #: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void