debian-mirror-gitlab/app/models/concerns/relative_positioning.rb

498 lines
16 KiB
Ruby
Raw Normal View History

2018-11-20 20:47:30 +05:30
# frozen_string_literal: true
2019-10-12 21:52:04 +05:30
# This module makes it possible to handle items as a list, where the order of items can be easily altered
# Requirements:
#
2020-10-24 23:57:45 +05:30
# The model must have the following named columns:
# - id: integer
# - relative_position: integer
2019-10-12 21:52:04 +05:30
#
2020-10-24 23:57:45 +05:30
# The model must support a concept of siblings via a child->parent relationship,
# to enable rebalancing and `GROUP BY` in queries.
# - example: project -> issues, project is the parent relation (issues table has a parent_id column)
#
# Two class methods must be defined when including this concern:
2019-10-12 21:52:04 +05:30
#
# include RelativePositioning
#
# # base query used for the position calculation
# def self.relative_positioning_query_base(issue)
# where(deleted: false)
# end
#
# # column that should be used in GROUP BY
# def self.relative_positioning_parent_column
# :project_id
# end
#
2017-08-17 22:00:37 +05:30
module RelativePositioning
extend ActiveSupport::Concern
2020-10-24 23:57:45 +05:30
STEPS = 10
IDEAL_DISTANCE = 2**(STEPS - 1) + 1
MIN_POSITION = Gitlab::Database::MIN_INT_VALUE
START_POSITION = 0
2017-08-17 22:00:37 +05:30
MAX_POSITION = Gitlab::Database::MAX_INT_VALUE
2020-10-24 23:57:45 +05:30
MAX_GAP = IDEAL_DISTANCE * 2
MIN_GAP = 2
2018-12-13 13:39:08 +05:30
2020-10-24 23:57:45 +05:30
NoSpaceLeft = Class.new(StandardError)
2019-02-15 15:39:39 +05:30
2020-10-24 23:57:45 +05:30
class_methods do
def move_nulls_to_end(objects)
move_nulls(objects, at_end: true)
end
2019-02-15 15:39:39 +05:30
2020-10-24 23:57:45 +05:30
def move_nulls_to_start(objects)
move_nulls(objects, at_end: false)
2018-12-13 13:39:08 +05:30
end
# This method takes two integer values (positions) and
# calculates the position between them. The range is huge as
2020-10-24 23:57:45 +05:30
# the maximum integer value is 2147483647.
#
# We avoid open ranges by clamping the range to [MIN_POSITION, MAX_POSITION].
#
# Then we handle one of three cases:
# - If the gap is too small, we raise NoSpaceLeft
# - If the gap is larger than MAX_GAP, we place the new position at most
# IDEAL_DISTANCE from the edge of the gap.
# - otherwise we place the new position at the midpoint.
#
# The new position will always satisfy: pos_before <= midpoint <= pos_after
#
# As a precondition, the gap between pos_before and pos_after MUST be >= 2.
# If the gap is too small, NoSpaceLeft is raised.
#
# This class method should only be called by instance methods of this module, which
# include handling for minimum gap size.
#
# @raises NoSpaceLeft
# @api private
2018-12-13 13:39:08 +05:30
def position_between(pos_before, pos_after)
pos_before ||= MIN_POSITION
pos_after ||= MAX_POSITION
pos_before, pos_after = [pos_before, pos_after].sort
2020-10-24 23:57:45 +05:30
gap_width = pos_after - pos_before
midpoint = [pos_after - 1, pos_before + (gap_width / 2)].min
2018-12-13 13:39:08 +05:30
2020-10-24 23:57:45 +05:30
if gap_width < MIN_GAP
raise NoSpaceLeft
elsif gap_width > MAX_GAP
2018-12-13 13:39:08 +05:30
if pos_before == MIN_POSITION
pos_after - IDEAL_DISTANCE
elsif pos_after == MAX_POSITION
pos_before + IDEAL_DISTANCE
else
2020-10-24 23:57:45 +05:30
midpoint
end
else
midpoint
end
end
private
# @api private
def gap_size(object, gaps:, at_end:, starting_from:)
total_width = IDEAL_DISTANCE * gaps
size = if at_end && starting_from + total_width >= MAX_POSITION
(MAX_POSITION - starting_from) / gaps
elsif !at_end && starting_from - total_width <= MIN_POSITION
(starting_from - MIN_POSITION) / gaps
else
IDEAL_DISTANCE
end
# Shift max elements leftwards if there isn't enough space
return [size, starting_from] if size >= MIN_GAP
order = at_end ? :desc : :asc
terminus = object
.send(:relative_siblings) # rubocop:disable GitlabSecurity/PublicSend
.where('relative_position IS NOT NULL')
.order(relative_position: order)
.first
if at_end
terminus.move_sequence_before(true)
max_relative_position = terminus.reset.relative_position
[[(MAX_POSITION - max_relative_position) / gaps, IDEAL_DISTANCE].min, max_relative_position]
else
terminus.move_sequence_after(true)
min_relative_position = terminus.reset.relative_position
[[(min_relative_position - MIN_POSITION) / gaps, IDEAL_DISTANCE].min, min_relative_position]
end
end
# @api private
# @param [Array<RelativePositioning>] objects The objects to give positions to. The relative
# order will be preserved (i.e. when this method returns,
# objects.first.relative_position < objects.last.relative_position)
# @param [Boolean] at_end: The placement.
# If `true`, then all objects with `null` positions are placed _after_
# all siblings with positions. If `false`, all objects with `null`
# positions are placed _before_ all siblings with positions.
# @returns [Number] The number of moved records.
def move_nulls(objects, at_end:)
objects = objects.reject(&:relative_position)
return 0 if objects.empty?
representative = objects.first
number_of_gaps = objects.size + 1 # 1 at left, one between each, and one at right
position = if at_end
representative.max_relative_position
else
representative.min_relative_position
end
position ||= START_POSITION # If there are no positioned siblings, start from START_POSITION
gap, position = gap_size(representative, gaps: number_of_gaps, at_end: at_end, starting_from: position)
# Raise if we could not make enough space
raise NoSpaceLeft if gap < MIN_GAP
indexed = objects.each_with_index.to_a
starting_from = at_end ? position : position - (gap * number_of_gaps)
# Some classes are polymorphic, and not all siblings are in the same table.
by_model = indexed.group_by { |pair| pair.first.class }
by_model.each do |model, pairs|
model.transaction do
pairs.each_slice(100) do |batch|
# These are known to be integers, one from the DB, and the other
# calculated by us, and thus safe to interpolate
values = batch.map do |obj, i|
pos = starting_from + gap * (i + 1)
obj.relative_position = pos
"(#{obj.id}, #{pos})"
end.join(', ')
model.connection.exec_query(<<~SQL, "UPDATE #{model.table_name} positions")
WITH cte(cte_id, new_pos) AS (
SELECT *
FROM (VALUES #{values}) as t (id, pos)
)
UPDATE #{model.table_name}
SET relative_position = cte.new_pos
FROM cte
WHERE cte_id = id
SQL
end
2018-12-13 13:39:08 +05:30
end
end
2020-10-24 23:57:45 +05:30
objects.size
2018-12-13 13:39:08 +05:30
end
end
2019-02-15 15:39:39 +05:30
def min_relative_position(&block)
calculate_relative_position('MIN', &block)
2018-03-17 18:26:18 +05:30
end
2019-02-15 15:39:39 +05:30
def max_relative_position(&block)
calculate_relative_position('MAX', &block)
2017-08-17 22:00:37 +05:30
end
2020-10-24 23:57:45 +05:30
def prev_relative_position(ignoring: nil)
2017-08-17 22:00:37 +05:30
prev_pos = nil
if self.relative_position
2019-02-15 15:39:39 +05:30
prev_pos = max_relative_position do |relation|
2020-10-24 23:57:45 +05:30
relation = relation.id_not_in(ignoring.id) if ignoring.present?
2019-02-15 15:39:39 +05:30
relation.where('relative_position < ?', self.relative_position)
end
2017-08-17 22:00:37 +05:30
end
prev_pos
end
2020-10-24 23:57:45 +05:30
def next_relative_position(ignoring: nil)
2017-08-17 22:00:37 +05:30
next_pos = nil
if self.relative_position
2019-02-15 15:39:39 +05:30
next_pos = min_relative_position do |relation|
2020-10-24 23:57:45 +05:30
relation = relation.id_not_in(ignoring.id) if ignoring.present?
2019-02-15 15:39:39 +05:30
relation.where('relative_position > ?', self.relative_position)
end
2017-08-17 22:00:37 +05:30
end
next_pos
end
def move_between(before, after)
return move_after(before) unless after
return move_before(after) unless before
2019-10-12 21:52:04 +05:30
before, after = after, before if after.relative_position < before.relative_position
2020-10-24 23:57:45 +05:30
pos_left = before.relative_position
pos_right = after.relative_position
if pos_right - pos_left < MIN_GAP
# Not enough room! Make space by shifting all previous elements to the left
# if there is enough space, else to the right
gap = after.send(:find_next_gap_before) # rubocop:disable GitlabSecurity/PublicSend
if gap.present?
after.move_sequence_before(next_gap: gap)
pos_left -= optimum_delta_for_gap(gap)
else
before.move_sequence_after
pos_right = after.reset.relative_position
end
2017-08-17 22:00:37 +05:30
end
2020-10-24 23:57:45 +05:30
new_position = self.class.position_between(pos_left, pos_right)
self.relative_position = new_position
2017-08-17 22:00:37 +05:30
end
def move_after(before = self)
pos_before = before.relative_position
2020-10-24 23:57:45 +05:30
pos_after = before.next_relative_position(ignoring: self)
if pos_before == MAX_POSITION || gap_too_small?(pos_after, pos_before)
gap = before.send(:find_next_gap_after) # rubocop:disable GitlabSecurity/PublicSend
2017-08-17 22:00:37 +05:30
2020-10-24 23:57:45 +05:30
if gap.nil?
before.move_sequence_before(true)
pos_before = before.reset.relative_position
else
before.move_sequence_after(next_gap: gap)
pos_after += optimum_delta_for_gap(gap)
end
2017-08-17 22:00:37 +05:30
end
2018-12-13 13:39:08 +05:30
self.relative_position = self.class.position_between(pos_before, pos_after)
2017-08-17 22:00:37 +05:30
end
def move_before(after = self)
pos_after = after.relative_position
2020-10-24 23:57:45 +05:30
pos_before = after.prev_relative_position(ignoring: self)
if pos_after == MIN_POSITION || gap_too_small?(pos_before, pos_after)
gap = after.send(:find_next_gap_before) # rubocop:disable GitlabSecurity/PublicSend
2017-08-17 22:00:37 +05:30
2020-10-24 23:57:45 +05:30
if gap.nil?
after.move_sequence_after(true)
pos_after = after.reset.relative_position
else
after.move_sequence_before(next_gap: gap)
pos_before -= optimum_delta_for_gap(gap)
end
2017-08-17 22:00:37 +05:30
end
2018-12-13 13:39:08 +05:30
self.relative_position = self.class.position_between(pos_before, pos_after)
2017-08-17 22:00:37 +05:30
end
def move_to_end
2020-10-24 23:57:45 +05:30
max_pos = max_relative_position
if max_pos.nil?
self.relative_position = START_POSITION
elsif gap_too_small?(max_pos, MAX_POSITION)
max = relative_siblings.order(Gitlab::Database.nulls_last_order('relative_position', 'DESC')).first
max.move_sequence_before(true)
max.reset
self.relative_position = self.class.position_between(max.relative_position, MAX_POSITION)
else
self.relative_position = self.class.position_between(max_pos, MAX_POSITION)
end
2017-08-17 22:00:37 +05:30
end
2018-03-17 18:26:18 +05:30
def move_to_start
2020-10-24 23:57:45 +05:30
min_pos = min_relative_position
if min_pos.nil?
self.relative_position = START_POSITION
elsif gap_too_small?(min_pos, MIN_POSITION)
min = relative_siblings.order(Gitlab::Database.nulls_last_order('relative_position', 'ASC')).first
min.move_sequence_after(true)
min.reset
self.relative_position = self.class.position_between(MIN_POSITION, min.relative_position)
else
self.relative_position = self.class.position_between(MIN_POSITION, min_pos)
end
2018-03-17 18:26:18 +05:30
end
2019-10-12 21:52:04 +05:30
# Moves the sequence before the current item to the middle of the next gap
2020-10-24 23:57:45 +05:30
# For example, we have
#
# 5 . . . . . 11 12 13 14 [15] 16 . 17
# -----------
#
# This moves the sequence [11 12 13 14] to [8 9 10 11], so we have:
#
# 5 . . 8 9 10 11 . . . [15] 16 . 17
# ---------
#
# Creating a gap to the left of the current item. We can understand this as
# dividing the 5 spaces between 5 and 11 into two smaller gaps of 2 and 3.
#
# If `include_self` is true, the current item will also be moved, creating a
# gap to the right of the current item:
#
# 5 . . 8 9 10 11 [14] . . . 16 . 17
# --------------
#
# As an optimization, the gap can be precalculated and passed to this method.
#
# @api private
# @raises NoSpaceLeft if the sequence cannot be moved
def move_sequence_before(include_self = false, next_gap: find_next_gap_before)
raise NoSpaceLeft unless next_gap.present?
2019-10-12 21:52:04 +05:30
delta = optimum_delta_for_gap(next_gap)
2020-10-24 23:57:45 +05:30
move_sequence(next_gap[:start], relative_position, -delta, include_self)
2017-08-17 22:00:37 +05:30
end
2019-10-12 21:52:04 +05:30
# Moves the sequence after the current item to the middle of the next gap
2020-10-24 23:57:45 +05:30
# For example, we have:
#
# 8 . 10 [11] 12 13 14 15 . . . . . 21
# -----------
#
# This moves the sequence [12 13 14 15] to [15 16 17 18], so we have:
#
# 8 . 10 [11] . . . 15 16 17 18 . . 21
# -----------
#
# Creating a gap to the right of the current item. We can understand this as
# dividing the 5 spaces between 15 and 21 into two smaller gaps of 3 and 2.
#
# If `include_self` is true, the current item will also be moved, creating a
# gap to the left of the current item:
#
# 8 . 10 . . . [14] 15 16 17 18 . . 21
# ----------------
#
# As an optimization, the gap can be precalculated and passed to this method.
#
# @api private
# @raises NoSpaceLeft if the sequence cannot be moved
def move_sequence_after(include_self = false, next_gap: find_next_gap_after)
raise NoSpaceLeft unless next_gap.present?
2019-10-12 21:52:04 +05:30
delta = optimum_delta_for_gap(next_gap)
2020-10-24 23:57:45 +05:30
move_sequence(relative_position, next_gap[:start], delta, include_self)
2017-08-17 22:00:37 +05:30
end
private
2020-10-24 23:57:45 +05:30
def gap_too_small?(pos_a, pos_b)
return false unless pos_a && pos_b
(pos_a - pos_b).abs < MIN_GAP
end
# Find the first suitable gap to the left of the current position.
#
# Satisfies the relations:
# - gap[:start] <= relative_position
# - abs(gap[:start] - gap[:end]) >= MIN_GAP
# - MIN_POSITION <= gap[:start] <= MAX_POSITION
# - MIN_POSITION <= gap[:end] <= MAX_POSITION
#
# Supposing that the current item is 13, and we have a sequence of items:
#
# 1 . . . 5 . . . . 11 12 [13] 14 . . 17
# ^---------^
#
# Then we return: `{ start: 11, end: 5 }`
#
# Here start refers to the end of the gap closest to the current item.
2019-10-12 21:52:04 +05:30
def find_next_gap_before
items_with_next_pos = scoped_items
.select('relative_position AS pos, LEAD(relative_position) OVER (ORDER BY relative_position DESC) AS next_pos')
.where('relative_position <= ?', relative_position)
.order(relative_position: :desc)
2020-10-24 23:57:45 +05:30
find_next_gap(items_with_next_pos, MIN_POSITION)
2019-10-12 21:52:04 +05:30
end
2020-10-24 23:57:45 +05:30
# Find the first suitable gap to the right of the current position.
#
# Satisfies the relations:
# - gap[:start] >= relative_position
# - abs(gap[:start] - gap[:end]) >= MIN_GAP
# - MIN_POSITION <= gap[:start] <= MAX_POSITION
# - MIN_POSITION <= gap[:end] <= MAX_POSITION
#
# Supposing the current item is 13, and that we have a sequence of items:
#
# 9 . . . [13] 14 15 . . . . 20 . . . 24
# ^---------^
#
# Then we return: `{ start: 15, end: 20 }`
#
# Here start refers to the end of the gap closest to the current item.
2019-10-12 21:52:04 +05:30
def find_next_gap_after
items_with_next_pos = scoped_items
.select('relative_position AS pos, LEAD(relative_position) OVER (ORDER BY relative_position ASC) AS next_pos')
.where('relative_position >= ?', relative_position)
.order(:relative_position)
2017-08-17 22:00:37 +05:30
2020-10-24 23:57:45 +05:30
find_next_gap(items_with_next_pos, MAX_POSITION)
2019-10-12 21:52:04 +05:30
end
2020-10-24 23:57:45 +05:30
def find_next_gap(items_with_next_pos, end_is_nil)
gap = self.class
.from(items_with_next_pos, :items)
.where('next_pos IS NULL OR ABS(pos::bigint - next_pos::bigint) >= ?', MIN_GAP)
.limit(1)
.pluck(:pos, :next_pos)
.first
return if gap.nil? || gap.first == end_is_nil
2019-10-12 21:52:04 +05:30
2020-10-24 23:57:45 +05:30
{ start: gap.first, end: gap.second || end_is_nil }
2019-10-12 21:52:04 +05:30
end
2017-08-17 22:00:37 +05:30
2019-10-12 21:52:04 +05:30
def optimum_delta_for_gap(gap)
delta = ((gap[:start] - gap[:end]) / 2.0).abs.ceil
[delta, IDEAL_DISTANCE].min
end
2020-10-24 23:57:45 +05:30
def move_sequence(start_pos, end_pos, delta, include_self = false)
relation = include_self ? scoped_items : relative_siblings
relation
2019-10-12 21:52:04 +05:30
.where('relative_position BETWEEN ? AND ?', start_pos, end_pos)
.update_all("relative_position = relative_position + #{delta}")
2017-08-17 22:00:37 +05:30
end
2019-02-15 15:39:39 +05:30
def calculate_relative_position(calculation)
# When calculating across projects, this is much more efficient than
# MAX(relative_position) without the GROUP BY, due to index usage:
2019-12-04 20:38:33 +05:30
# https://gitlab.com/gitlab-org/gitlab-foss/issues/54276#note_119340977
2019-10-12 21:52:04 +05:30
relation = scoped_items
2019-02-15 15:39:39 +05:30
.order(Gitlab::Database.nulls_last_order('position', 'DESC'))
2019-10-12 21:52:04 +05:30
.group(self.class.relative_positioning_parent_column)
2019-02-15 15:39:39 +05:30
.limit(1)
relation = yield relation if block_given?
relation
2019-10-12 21:52:04 +05:30
.pluck(self.class.relative_positioning_parent_column, Arel.sql("#{calculation}(relative_position) AS position"))
2020-03-13 15:44:24 +05:30
.first&.last
2019-02-15 15:39:39 +05:30
end
2019-10-12 21:52:04 +05:30
2020-10-24 23:57:45 +05:30
def relative_siblings(relation = scoped_items)
relation.id_not_in(id)
end
2019-10-12 21:52:04 +05:30
def scoped_items
self.class.relative_positioning_query_base(self)
end
2017-08-17 22:00:37 +05:30
end