rotulus 0.2.0

data/lib/rotulus/column.rb

@@ -0,0 +1,157 @@
+module Rotulus
+  class Column
+    attr_reader :model, :name, :direction, :nulls
+
+    # Creates a Column object representing a table column in the "ORDER BY" expression.
+    #
+    # @param model [Class] the ActiveRecord model class name where this column belongs
+    # @param name [String] the column name. Columns from joined tables are
+    #   prefixed with the joined table's name/alias (e.g. +some_table.column+).
+    # @param direction [Symbol] the sort direction, +:asc+ or +:desc+. Default: +:asc+.
+    # @param nullable [Boolean] whether a null value is expected for this column in the result.
+    #  Note that for queries with table JOINs, a column could have a null value even
+    #  if the column doesn't allow nulls in its table so :nullable might need to be set
+    #  to +true+ for such cases.
+    #  Default: +true+ if :nullable option value is nil and the column is defined as
+    #  nullable in its table otherwise, false.
+    # @param nulls [Symbol] null values sorting, +:first+ for +NULLS FIRST+ and
+    #  +:last+ for +NULLS LAST+. Applicable only if column is nullable.
+    # @param distinct [Boolean] whether the column value is expected to be unique in the result.
+    #  Note that for queries with table JOINs, multiple rows could have the same column
+    #  value even if the column has a unique index defined in its table so :distinct might
+    #  need to be set to +false+ for such cases.
+    #  Default: true if :distinct option value is nil and the column is the PK of its
+    #  table otherwise, false.
+    #
+    def initialize(model, name, direction: :asc, nullable: nil, nulls: nil, distinct: nil)
+      @model = model
+      @name = name.to_s
+      unless name_valid?
+        raise Rotulus::InvalidColumnError.new("Column/table name must contain letters, digits (0-9), or \
+          underscores and must begin with a letter or underscore.".squish)
+      end
+
+      @direction = direction.to_s.downcase == 'desc' ? :desc : :asc
+      @distinct = (distinct.nil? ? primary_key? : distinct).presence || false
+      @nullable = (nullable.nil? ? metadata&.null : nullable).presence || false
+      @nulls = nulls_order(nulls)
+    end
+
+    def self.select_alias_to_name(select_alias)
+      select_alias.gsub('cursor___', '').gsub('__', '.')
+    end
+
+    def self.select_alias(name)
+      "cursor___#{name.to_s.gsub('.', '__')}"
+    end
+
+    # Mark the column as the 'leftmost' column in the 'ORDER BY' SQL (column with highest sort priority)
+    def as_leftmost!
+      @leftmost = true
+
+      self
+    end
+
+    def leftmost?
+      @leftmost
+    end
+
+    def asc?
+      direction == :asc
+    end
+
+    def desc?
+      !asc?
+    end
+
+    def distinct?
+      @distinct
+    end
+
+    def nullable?
+      @nullable
+    end
+
+    def nulls_first?
+      nulls == :first
+    end
+
+    def nulls_last?
+      nulls == :last
+    end
+
+    def unprefixed_name
+      @unprefixed_name ||= name.split('.').last
+    end
+
+    def prefixed_name
+      @prefixed_name ||= if !name_has_prefix?
+                           "#{model.table_name}.#{name}"
+                         else
+                           name
+                         end
+    end
+
+    def select_alias
+      self.class.select_alias(prefixed_name)
+    end
+
+    def to_h
+      h = {
+        direction: direction,
+        nullable: nullable?,
+        distinct: distinct?
+      }
+      h[:nulls] = nulls if nullable?
+
+      { prefixed_name => h }
+    end
+
+    def reversed_order_sql
+      return Rotulus.db.reversed_order_sql(prefixed_name, direction) unless nullable?
+
+      Rotulus.db.reversed_nullable_order_sql(prefixed_name, direction, nulls)
+    end
+
+    def order_sql
+      return Rotulus.db.order_sql(prefixed_name, direction) unless nullable?
+
+      Rotulus.db.nullable_order_sql(prefixed_name, direction, nulls)
+    end
+
+    def select_sql
+      "#{prefixed_name} as #{select_alias}"
+    end
+
+    private
+
+    def metadata
+      model.columns_hash[unprefixed_name]
+    end
+
+    def name_has_prefix?
+      return @name_has_prefix if instance_variable_defined?(:@name_has_prefix)
+
+      @name_has_prefix = name.include?('.')
+    end
+
+    # Only alphanumeric columns and with or without underscores and table/alias prefix are allowed.
+    def name_valid?
+      return false if name.blank?
+
+      !!(name =~ /^([[:alpha:]_][[:alnum:]_]*)(\.([[:alpha:]_][[:alnum:]_]*))*$/)
+    end
+
+    def nulls_order(nulls)
+      return nil unless nullable?
+      return :last if nulls.to_s.downcase == 'last'
+      return :first if nulls.to_s.downcase == 'first'
+
+      Rotulus.db.default_nulls_order(direction)
+    end
+
+    def primary_key?
+      unprefixed_name == model.primary_key
+    end
+  end
+end

data/lib/rotulus/column_condition_builder.rb

@@ -0,0 +1,115 @@
+module Rotulus
+  class ColumnConditionBuilder
+    # Generates a condition builder instance that builds an SQL condition
+    # to filter the preceding or succeeding records given a Column instance and its
+    # value.
+    #
+    # @param column [Rotulus::Column] ordered column
+    # @param value [Object] the column value for a specific reference record
+    # @param direction [Symbol] the seek direction, `:next` or `:prev`
+    # @param tie_breaker_sql [Symbol] in case :column is not distinct, a 'tie-breaker' SQL
+    #  condition is needed to ensure stable pagination. This condition is generated from the (distinct)
+    #  columns with lower precedence in the ORDER BY column list. For example, in
+    #  "ORDER BY first_name asc, ssn desc", multiple records may exist with the same 'first_name' value.
+    #  The distinct column 'ssn' in the order definition will be the tie-breaker. If no
+    #  distinct column is defined in the order definition, the PK will be the tie-breaker.
+    def initialize(column, value, direction, tie_breaker_sql = nil)
+      @column = column
+      @value = value
+      @direction = direction
+      @tie_breaker_sql = tie_breaker_sql
+    end
+
+    def build
+      return filter_condition unless column.nullable?
+
+      nullable_filter_condition
+    end
+
+    private
+
+    attr_reader :column, :value, :direction, :tie_breaker_sql
+    delegate :nulls_first?, :nulls_last?, to: :column, prefix: false
+
+    def filter_condition
+      return seek_condition if column.distinct?
+
+      prefilter("#{seek_condition} OR (#{tie_break(identity)})")
+    end
+
+    def nullable_filter_condition
+      if seek_to_null_direction?
+        return tie_break null_condition if value.nil?
+
+        condition = "#{seek_condition} OR #{null_condition}"
+        return condition if column.distinct?
+
+        prefilter("(#{condition}) OR (#{tie_break(identity)})")
+      else
+        return filter_condition unless value.nil?
+
+        "#{not_null_condition} OR (#{tie_break(null_condition)})"
+      end
+    end
+
+    def identity
+      "#{column.prefixed_name} = #{quoted_value}"
+    end
+
+    # Pre-filter leftmost ordered column for perfomance if column is non-distinct
+    # https://use-the-index-luke.com/sql/partial-results/fetch-next-page#sb-equivalent-logic
+    def prefilter(condition)
+      return condition unless column.leftmost?
+
+      if column.nullable? && seek_to_null_direction?
+        return "(#{seek_condition(:inclusive)} OR #{null_condition}) AND (#{condition})"
+      end
+
+      "#{seek_condition(:inclusive)} AND (#{condition})"
+    end
+
+    def tie_break(condition)
+      return condition if tie_breaker_sql.blank?
+
+      "#{condition} AND #{tie_breaker_sql}"
+    end
+
+    def null_condition
+      "#{column.prefixed_name} IS NULL"
+    end
+
+    def not_null_condition
+      "#{column.prefixed_name} IS NOT NULL"
+    end
+
+    def seek_condition(inclusivity = :exclusive)
+      operator = seek_operators[direction][column.direction]
+      operator = "#{operator}=" if inclusivity == :inclusive
+
+      "#{column.prefixed_name} #{operator} #{quoted_value}"
+    end
+
+    def seek_operators
+      @seek_operators ||= { next: { asc: '>', desc: '<' },
+                            prev: { asc: '<', desc: '>' } }
+    end
+
+    def seek_next?
+      direction == :next
+    end
+
+    def seek_prev?
+      !seek_next?
+    end
+
+    def seek_to_null_direction?
+      (nulls_first? && seek_prev?) || (nulls_last? && seek_next?)
+    end
+
+    def quoted_value
+      return value unless value.is_a?(String)
+
+      ActiveRecord::Base.connection.quote(value)
+    end
+  end
+end

data/lib/rotulus/configuration.rb

@@ -0,0 +1,74 @@
+module Rotulus
+  class Configuration
+    attr_accessor :secret
+
+    def initialize
+      @page_default_limit = default_limit
+      @page_max_limit = default_max_limit
+      @secret = ENV['ROTULUS_SECRET']
+      @token_expires_in = 259200
+      @cursor_class = default_cursor_class
+    end
+
+    def page_default_limit=(limit)
+      @page_default_limit = limit.to_i
+    end
+
+    def page_default_limit
+      limit = @page_default_limit
+      limit = default_limit unless limit.positive?
+      limit = page_max_limit if limit > page_max_limit
+      limit
+    end
+
+    def page_max_limit=(limit)
+      @page_max_limit = limit.to_i
+    end
+
+    def page_max_limit
+      return @page_max_limit if @page_max_limit.positive?
+
+      default_max_limit
+    end
+
+    def token_expires_in=(expire_in_seconds)
+      @token_expires_in = expire_in_seconds.to_i
+    end
+
+    def token_expires_in
+      return @token_expires_in if @token_expires_in.positive?
+
+      nil
+    end
+
+    def cursor_class=(cursor_class)
+      @cursor_class = cursor_class.is_a?(String) ? cursor_class.constantize : cursor_class
+    end
+
+    def cursor_class
+      @cursor_class || default_cursor_class
+    end
+
+    private
+
+    def default_cursor_class
+      Rotulus::Cursor
+    end
+
+    def default_limit
+      5
+    end
+
+    def default_max_limit
+      50
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield configuration if block_given?
+  end
+end

data/lib/rotulus/cursor.rb

@@ -0,0 +1,152 @@
+require 'base64'
+
+module Rotulus
+  class Cursor
+    class << self
+      #  Initialize a Cursor instance for the given page instance and encoded token.
+      #
+      #  @param page [Page] Page instance
+      #  @param token [String] Base64-encoded string data
+      #  @return [Cursor] Cursor
+      #
+      #  @raise [InvalidCursor] if the cursor is no longer consistent to the page's ActiveRecord
+      #    relation filters, sorting, limit, or if the encoded cursor data was tampered.
+      def for_page_and_token!(page, token)
+        data = decode(token)
+        reference_record = Record.new(page, data[:f])
+        direction = data[:d]
+        created_at = Time.at(data[:c]).utc
+        state = data[:s].presence
+
+        cursor = new(reference_record, direction, created_at: created_at)
+
+        if cursor.state != state
+          raise InvalidCursor.new('Invalid cursor possibly due to filter, order, or limit changed')
+        end
+
+        cursor
+      end
+
+      #  Decode the given encoded cursor token
+      #
+      #  @param token [String] Encoded cursor token
+      #  @return [Hash] Cursor data hash containing the cursor direction(:next, :prev),
+      #    cursor's state, and the ordered column values of the reference record: last record
+      #    of the previous page if page direction is `:next` or the first record of the next
+      #    page if page direction is `:prev`.
+      def decode(token)
+        Oj.load(Base64.urlsafe_decode64(token))
+      rescue ArgumentError => e
+        raise InvalidCursor.new("Invalid Cursor: #{e.message}")
+      end
+
+      #  Encode cursor data hash
+      #
+      #  @param token_data [Hash] Cursor token data hash
+      #  @return token [String] String token for this cursor that can be used as param to Page#at.
+      def encode(token_data)
+        Base64.urlsafe_encode64(Oj.dump(token_data, symbol_keys: true))
+      end
+    end
+
+    attr_reader :record, :direction, :created_at
+
+    delegate :page, to: :record, prefix: false
+
+    # @param record [Record] the last(first if direction is `:prev`) record of page containing
+    #   the ordered column's values that will be used to generate the next/prev page query.
+    # @param direction [Symbol] the cursor direction, `:next` for next page or `:prev` for
+    #   previous page
+    # @param created_at [Time] only needed when deserializing a Cursor from a token. The time
+    #   when the cursor was last initialized. see Cursor.from_page_and_token!
+    def initialize(record, direction, created_at: nil)
+      @record = record
+      @direction = direction.to_sym
+      @created_at = created_at.presence || Time.current
+
+      validate!
+    end
+
+    # @return [Boolean] returns true if the cursor should retrieve the 'next' records from the last
+    #   record of the previous page. Otherwise, returns false.
+    def next?
+      direction == :next
+    end
+
+    # @return [Boolean] returns true if the cursor should retrieve the 'previous' records from the
+    #   first record of a page. Otherwise, returns false.
+    def prev?
+      !next?
+    end
+
+    # Generate the SQL condition to filter the records of the next/previous page. The condition is
+    # generated based on the order definition and the referenced record's values.
+    #
+    # @return [String] the SQL 'where' condition to get the next or previous page's records.
+    def sql
+      @sql ||= Arel.sql(record.sql_seek_condition(direction))
+    end
+
+    # Generate the token: a Base64-encoded string representation of this cursor
+    #
+    # @return [String] the token encoded in Base64.
+    def to_token
+      @token ||= self.class.encode(f: record.values,
+                                   d: direction,
+                                   s: state,
+                                   c: created_at.to_i)
+    end
+    alias to_s to_token
+
+    # Generate a 'state' string so we can detect whether the cursor data is no longer consistent to
+    # the AR filter, limit, or order definition. This also provides a mechanism to detect if
+    # any token data was tampered.
+    #
+    # @return [String] the hashed state
+    def state
+      state_data = "#{page.state}#{record.state}"
+      state_data << "#{direction}#{created_at.to_i}#{secret}"
+
+      Digest::MD5.hexdigest(state_data)
+    end
+
+    # Checks if the cursor is expired
+    #
+    # @return [Boolean] returns true if cursor is expired
+    def expired?
+      return false if config.token_expires_in.nil? || created_at.nil?
+
+      (created_at + config.token_expires_in) < Time.current
+    end
+
+    private
+
+    # Checks whether the cursor is valid
+    #
+    # @return [Boolean]
+    #
+    # @raise [InvalidCursorDirection] if the cursor direction is not valid.
+    # @raise [ExpiredCursor] if the cursor is expired.
+    def validate!
+      raise ExpiredCursor.new('Cursor token expired') if expired?
+
+      return if direction_valid?
+
+      raise InvalidCursorDirection.new('Cursor direction should either be :prev or :next.')
+    end
+
+    def direction_valid?
+      %i[prev next].include?(direction)
+    end
+
+    def secret
+      return config.secret if config.secret.present?
+
+      raise ConfigurationError.new('missing :secret configuration.')
+    end
+
+    def config
+      @config ||= Rotulus.configuration
+    end
+  end
+end

data/lib/rotulus/db/database.rb

@@ -0,0 +1,66 @@
+module Rotulus
+  module DB
+    class Database
+      def name
+        @name ||= self.class.name.split('::').last.downcase
+      end
+
+      def select_all_sql(table_name)
+        "\"#{table_name}\".*"
+      end
+
+      def nulls_order_sql(nulls)
+        return 'nulls first' if nulls == :first
+
+        'nulls last'
+      end
+
+      def order_sql(column_name, sort_direction)
+        "#{column_name} #{sort_direction}"
+      end
+
+      def reversed_order_sql(column_name, sort_direction)
+        "#{column_name} #{reverse_sort_direction(sort_direction)}"
+      end
+
+      def nullable_order_sql(column_name, sort_direction, nulls)
+        sql = order_sql(column_name, sort_direction)
+        return sql if nulls_in_default_order?(sort_direction, nulls)
+
+        "#{sql} #{nulls_order_sql(nulls)}"
+      end
+
+      def reversed_nullable_order_sql(column_name, sort_direction, nulls)
+        sql = reversed_order_sql(column_name, sort_direction)
+
+        nulls = reverse_nulls(nulls)
+        return sql if nulls_in_default_order?(reverse_sort_direction(sort_direction), nulls)
+
+        "#{sql} #{nulls_order_sql(nulls)}"
+      end
+
+      def nulls_in_default_order?(sort_direction, nulls)
+        nulls == default_nulls_order(sort_direction)
+      end
+
+      # SQLite and MySQL considers NULL values to be smaller than any other values.
+      # https://www.sqlite.org/lang_select.html#orderby
+      # https://dev.mysql.com/doc/refman/8.0/en/working-with-null.html
+      def default_nulls_order(sort_direction)
+        return :first if sort_direction == :asc
+
+        :last
+      end
+
+      private
+
+      def reverse_sort_direction(sort_direction)
+        sort_direction == :asc ? :desc : :asc
+      end
+
+      def reverse_nulls(nulls)
+        nulls == :first ? :last : :first
+      end
+    end
+  end
+end

data/lib/rotulus/db/mysql.rb

@@ -0,0 +1,31 @@
+module Rotulus
+  module DB
+    class MySQL < Database
+      def select_all_sql(table_name)
+        "`#{table_name}`.*"
+      end
+
+      def nulls_order_sql(nulls)
+        return 'is not null' if nulls == :first
+
+        'is null'
+      end
+
+      def nullable_order_sql(column_name, sort_direction, nulls)
+        sql = order_sql(column_name, sort_direction)
+        return sql if nulls_in_default_order?(sort_direction, nulls)
+
+        "#{column_name} #{nulls_order_sql(nulls)}, #{sql}"
+      end
+
+      def reversed_nullable_order_sql(column_name, sort_direction, nulls)
+        sql = reversed_order_sql(column_name, sort_direction)
+
+        nulls = reverse_nulls(nulls)
+        return sql if nulls_in_default_order?(reverse_sort_direction(sort_direction), nulls)
+
+        "#{column_name} #{nulls_order_sql(nulls)}, #{sql}"
+      end
+    end
+  end
+end

data/lib/rotulus/db/postgresql.rb

@@ -0,0 +1,13 @@
+module Rotulus
+  module DB
+    class PostgreSQL < Database
+      # PG considers NULL values to be larger than any other values.
+      # https://www.postgresql.org/docs/current/queries-order.html
+      def default_nulls_order(sort_direction)
+        return :last if sort_direction == :asc
+
+        :first
+      end
+    end
+  end
+end

data/lib/rotulus/db/sqlite.rb

@@ -0,0 +1,6 @@
+module Rotulus
+  module DB
+    class SQLite < Database
+    end
+  end
+end