pack_api 1.0.0

data/lib/pack_api/models/pagination/opaque_token_v2.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'brotli'
+
+module PackAPI::Pagination
+  class OpaqueTokenV2
+    def self.create(unencoded)
+      Base64.strict_encode64(Brotli.deflate(unencoded.to_json))
+    end
+
+    def self.parse(encoded)
+      raise JSON::ParserError if encoded.nil?
+
+      decoded = Base64.strict_decode64(encoded)
+      decompressed = Brotli.inflate(decoded)
+      JSON.parse(decompressed, symbolize_names: true)
+    end
+  end
+end

data/lib/pack_api/models/pagination/paginator.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+##
+# Enable paged access to large record sets.
+#
+# For any given query and sort, limit the returned item count, and provide access to adjacent subsets of the records.
+# An opaque token (aka "cursor") is created and passed to the caller for the following "pages" of data:
+#   - next page
+#   - previous page
+#   - first page
+#   - last page
+#
+# A cursor acts like a bookmark to a record in a recordset.
+#
+# The pagination strategy used is the most basic one: Limit-Offset.
+# More sophisticated ones exist (https://www.citusdata.com/blog/2016/03/30/five-ways-to-paginate/)
+# and can be implemented as needed.
+#
+# Construct an object of this type using the {PaginatorBuilder}
+# The various *_cursor methods return opaque tokens representing {Paginator} objects
+# They should be parsed using the {PaginatorCursor} class.
+#
+module PackAPI::Pagination
+  class Paginator
+    ###
+    # @param [Hash] query The query parameters used to define the recordset.
+    # @param [String|Symbol|Hash|Arel] sort The ordering used to define the recordset
+    # @param [Integer|:all] per_page The count of items to include on each result page, or :all for single page results
+    # @param [Integer] offset The starting index of the next result page
+    # @param [Integer] total_items The count of items in the result set
+    # @param [Any|nil] metadata optional, extra data structure to be passed along with the cursor
+    attr_accessor :query, :sort, :total_items, :per_page, :offset, :metadata
+
+    DEFAULT_PER_PAGE = 20
+    DEFAULT_SORT = 'id asc'
+
+    ###
+    # The range of items included in the results.
+    def item_range
+      return 0..0 if per_page != :all && per_page.zero?
+
+      lower_bound = offset + 1
+      upper_bound = per_page == :all ?
+                      total_items :
+                      [(offset + per_page), total_items].min
+      lower_bound..upper_bound
+    end
+
+    ###
+    # Represent the record set as a cursor-- this captures the current search criteria (filters, sort, etc.)
+    def recordset_cursor
+      make_cursor(recordset_cursor_params)
+    end
+
+    ###
+    # Represents a single page of results in the current record set-- the "current" page
+    def current_page_cursor
+      make_cursor(current_page_cursor_params)
+    end
+
+    ###
+    # Represents a single page of results in the current record set-- the "next" N results
+    def next_page_cursor
+      make_cursor(next_page_params)
+    end
+
+    ###
+    # Represents a single page of results in the current record set-- the "previous" N results
+    def previous_page_cursor
+      make_cursor(previous_page_params)
+    end
+
+    ###
+    # Represents a single page of results in the current record set-- the "first" N results
+    def first_page_cursor
+      make_cursor(first_page_params)
+    end
+
+    ###
+    # Represents a single page of results in the current record set-- the "last" N results
+    def last_page_cursor
+      make_cursor(last_page_params)
+    end
+
+    def limit
+      return nil if per_page == :all
+
+      per_page
+    end
+
+    private
+
+    def more_pages?
+      return false if per_page == :all || per_page.zero?
+
+      offset + per_page < total_items
+    end
+
+    def recordset_cursor_params
+      cursor_params.deep_merge(offset: 0, per_page: :all, metadata: { kind: :recordset })
+    end
+
+    def current_page_cursor_params
+      return nil if per_page != :all && per_page.zero?
+
+      cursor_params.deep_merge(offset: offset, metadata: { kind: :current_page })
+    end
+
+    def next_page_params
+      return nil unless more_pages?
+
+      cursor_params.deep_merge(offset: offset + per_page, metadata: { kind: :next_page })
+    end
+
+    def previous_page_params
+      return nil if offset.zero?
+
+      cursor_params.deep_merge(offset: offset - per_page, metadata: { kind: :previous_page })
+    end
+
+    def first_page_params
+      return nil if offset.zero?
+
+      cursor_params.deep_merge(offset: 0, metadata: { kind: :first_page })
+    end
+
+    def last_page_params
+      return nil unless more_pages?
+
+      last_page_offset = (last_item_offset / per_page).floor * per_page
+      cursor_params.deep_merge(offset: last_page_offset, metadata: { kind: :last_page })
+    end
+
+    def last_item_offset
+      total_items - 1
+    end
+
+    def make_cursor(params)
+      return nil if params.nil?
+
+      PaginatorCursor.create(**params)
+    end
+
+    def cursor_params
+      {
+        offset:,
+        sort:,
+        total_items:,
+        per_page:,
+        query:,
+        metadata:
+      }
+    end
+  end
+end

data/lib/pack_api/models/pagination/paginator_builder.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# Make it easier to correctly instantiate a Paginator object, given that a few different
+# use cases exist each having different data (arguments).
+#
+# This is an application of the Builder pattern (see https://refactoring.guru/design-patterns/builder) for Ruby.
+#
+# Two scenarios exist for constructing a Paginator object:
+#
+# 1. Starting a new query.
+#   Uses the following parameters:
+#   * query - filters used to define the recordset
+#   * sort - ordering used to define the recordset
+#   * per_page - count of items to include on each result page
+#   * offset - starting index of the next result page
+#   * total_items - count of items in the result set, if known
+#
+# OR
+#
+# 2. Continuing an existing query
+#   Uses the following parameters:
+#   * a pagination cursor
+#   * sort (optional) - Used to override the sort order of the cursor; effectively creates a new query
+#   * per_page (optional) - Used to override the per_page of the cursor; will limit the count of results in the
+#
+module PackAPI::Pagination
+  class PaginatorBuilder
+    attr_accessor :paginator
+
+    def self.build
+      builder = new
+      yield(builder)
+      builder.paginator
+    end
+
+    def initialize
+      @paginator = Paginator.new
+    end
+
+    def set_cursor(cursor:, per_page: nil, sort: nil)
+      cursor_params = PaginatorCursor.parse(cursor)
+      effective_per_page = per_page.presence || cursor_params[:per_page]
+      effective_per_page = :all if effective_per_page.to_s == 'all'
+
+      @paginator.query = cursor_params[:query]
+      @paginator.total_items = cursor_params[:total_items]
+      @paginator.per_page = effective_per_page
+      @paginator.sort = sort.presence || cursor_params[:sort]
+      @paginator.offset = effective_offset(cursor_params, sort)
+      @paginator.metadata = cursor_params[:metadata]
+    end
+
+    ###
+    # @param [Proc<Hash>|Hash] query The query parameters used to define the recordset.
+    # @param [String|Symbol|Hash|Arel] sort The ordering used to define the recordset
+    # @param [Integer|:all] per_page The count of items to include on each result page, or :all for single page results
+    # @param [Integer|nil] offset The starting index of the next result page
+    # @param [Integer|nil] total_items The count of items in the result set, if known.
+    # @param [Any|nil] metadata Any extra data structure to be passed along with the cursor
+    def set_params(query: nil, sort: nil, total_items: nil, per_page: nil, offset: nil, metadata: nil)
+      @paginator.query ||= {}
+      if query.present?
+        original_query = @paginator.query
+        @paginator.query = @paginator.query.deep_merge(resolve_query_params(query).deep_symbolize_keys)
+        @recordset_changed = original_query.to_json != @paginator.query.to_json
+      end
+
+      @paginator.sort ||= Paginator::DEFAULT_SORT
+      if sort.present?
+        @recordset_changed = sort.to_json != @paginator.sort.to_json
+        @paginator.sort = sort.presence
+      end
+
+      @paginator.total_items ||= 0
+      if total_items.present?
+        @paginator.total_items = total_items
+      end
+
+      @paginator.offset ||= 0
+      if offset.present?
+        @paginator.offset = offset
+      elsif @recordset_changed
+        @paginator.offset = 0
+      end
+
+      @paginator.per_page ||= Paginator::DEFAULT_PER_PAGE
+      if per_page.present?
+        @paginator.per_page = per_page
+        @paginator.offset = 0 if per_page == :all
+      end
+
+      @paginator.metadata ||= metadata
+    end
+
+    private
+
+    def effective_offset(cursor_params, sort)
+      sort_changed = sort.to_json != cursor_params[:sort].to_json
+      sort_override = sort.present? && sort_changed
+      sort_override ?
+        0 :
+        cursor_params[:offset]
+    end
+
+    def resolve_query_params(query)
+      query.is_a?(Proc) ?
+        query.call :
+        query
+    end
+
+  end
+end

data/lib/pack_api/models/pagination/paginator_cursor.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module PackAPI::Pagination
+  class PaginatorCursor
+    MAX_LENGTH = 2048
+    CACHE_KEY_PREFIX = 'paginator_cursor'
+    CACHE_EXPIRES_IN = 8.hours
+
+    class << self
+      def create(query:, sort:, total_items:, offset:, per_page:, metadata: nil)
+        sort_ready_to_serialize = SqlLiteralSerializer.serialize(sort)
+        cursor_params = { query:, sort: sort_ready_to_serialize, total_items:, offset:, per_page:, metadata: }
+        token = OpaqueTokenV2.create(cursor_params)
+        return token if token.size <= MAX_LENGTH
+
+        cache_key = generate_cache_key
+        Rails.cache.write(cache_key, cursor_params, expires_in: CACHE_EXPIRES_IN)
+        OpaqueTokenV2.create(cache_key)
+      end
+
+      def parse(encoded)
+        decoded = parse_opaque_token(encoded)
+        decoded = decode_cache_key(decoded) if decoded.is_a?(String)
+        decoded[:sort] = deserialize_sort_args(decoded)
+        decoded
+      end
+
+      private
+
+      def parse_opaque_token(encoded)
+        OpaqueTokenV2.parse(encoded)
+      rescue ArgumentError, Brotli::Error, JSON::ParserError => e
+        raise_error(e.message)
+      end
+
+      def raise_error(message)
+        raise(PackAPI::InternalError, "un-parsable paginator cursor: #{message}")
+      end
+
+      def decode_cache_key(cache_key)
+        data = Rails.cache.read(cache_key)
+        raise(PackAPI::InternalError, "no data found in cache for key #{cache_key}") if data.nil?
+
+        data
+      end
+
+      def generate_cache_key
+        "#{CACHE_KEY_PREFIX}:#{SecureRandom.uuid}"
+      end
+
+      def deserialize_sort_args(cursor)
+        SqlLiteralSerializer.deserialize(cursor[:sort])
+      rescue TypeError => e
+        raise_error(e.message)
+      end
+
+      # in order to recognize Arel::Nodes::SqlLiteral during parsing,
+      # we need to serialize it differently than a string
+      class SqlLiteralSerializer
+        def self.serialize(args)
+          return { sql_literal: { raw_sql: args.to_s } } if args.is_a?(Arel::Nodes::SqlLiteral)
+          return args unless args.is_a?(Hash)
+
+          args.map.with_index do |entry, index|
+            next entry unless entry[0].is_a?(Arel::Nodes::SqlLiteral)
+
+            ["sql_literal_#{index + 1}", { raw_sql: entry[0].to_s, hash_value: entry[1] }]
+          end.to_h
+        end
+
+        def self.deserialize(args)
+          return args unless args.is_a?(Hash)
+          return Arel.sql(args[:sql_literal][:raw_sql]) if args.key?(:sql_literal)
+
+          args.to_h do |key, value|
+            next [key, value] unless key.start_with?('sql_literal_')
+
+            [Arel.sql(value[:raw_sql]), value[:hash_value]]
+          end
+        end
+      end
+    end
+
+
+  end
+end

data/lib/pack_api/models/pagination/snapshot_paginator.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module PackAPI::Pagination
+
+  ###
+  # Current Page Snapshot Query is a query that targets the records in a given page of
+  # a record set (regardless of how those records may change state). Whereas the contents of
+  # the nth page in a record set may change, the cached results query for that same page will not.
+  #
+  # This class represents the paginator for such a query.
+  class SnapshotPaginator
+    METADATA_KEY = :snapshot
+
+    attr_accessor :paginator, :results, :cursor
+
+    ###
+    # Create a snapshot from the current page results of a record set.
+    def self.cursor_for_results(results, table_name:, collection_key:)
+      offsets = {}
+      case_statement = results.map.with_index do |record, index|
+        record_id = record.send(collection_key)
+        offsets[record_id.to_s] = index.to_s
+        # Use SQL standard CAST to convert both sides to strings for comparison
+        "WHEN CAST(\"#{table_name}\".\"#{collection_key}\" AS VARCHAR) = '#{record_id}' THEN #{index}"
+      end
+      sort_sql = "CASE #{case_statement.join("\n")} END"
+      filters = { collection_key => results.pluck(collection_key) }
+      paginator = PaginatorBuilder.build do |builder|
+        builder.set_params(query: { filters: },
+                           metadata: { METADATA_KEY => true, offsets:, collection_key: },
+                           sort: Arel.sql(sort_sql),
+                           total_items: results.size,
+                           per_page: results.size)
+      end
+      paginator.current_page_cursor
+    end
+
+    def initialize(paginator)
+      raise PackAPI::InternalError, 'Paginator does not represent CachedResultsQuery' if paginator.metadata.nil?
+
+      @paginator = paginator
+    end
+
+    ###
+    # Update the query to focus the result onto the given record within the snapshot.
+    # If no record_id is provided, it will attempt to guess the record_id based on the current paginator state.
+    # NOTE This method assumes that the paginator.total_items has already been updated to reflect the query's count.
+    def apply_to(query, record_id: nil)
+      if has_valid_offsets?
+        # if no record_id is provided, no customization is needed
+        return query unless record_id.present?
+
+        self.target_record_id = record_id
+        updated_query = query.offset(paginator.offset).limit(paginator.limit)
+        @results = updated_query.to_a
+        @cursor = paginator.current_page_cursor
+        updated_query
+      else
+        # unless we have either a record_id or an offset, there is no customization needed
+        return query unless paginator.offset.present? || record_id.present?
+
+        # Step 1: If we don't have a record_id, try to guess what record_id the user was trying to access
+        record_id ||= target_record_id
+
+        # Step 2: Fetch all the records in the snapshot -- remove the offset and limits on the current query
+        snapshot_results = query.unscope(:offset, :limit).to_a
+
+        # Step 3: Update the offsets based on the current query results
+        update_offsets(snapshot_results)
+
+        # Step 4: get the correct offset for the given record_id
+        self.target_record_id = record_id
+
+        # Step 5: Filter the results to just the record_id
+        collection_key = paginator.metadata[:collection_key]
+        @results = snapshot_results.select { it.send(collection_key).to_s == record_id.to_s }
+        @cursor = paginator.current_page_cursor
+        query.offset(paginator.offset).limit(paginator.limit)
+      end
+    end
+
+    ###
+    # Is the paginator one produced by this class?
+    def self.generated?(paginator)
+      paginator.metadata&.fetch(METADATA_KEY, nil).presence
+    end
+
+    private
+
+    def has_valid_offsets?
+      paginator.metadata[:offsets].size == paginator.total_items
+    end
+
+    ###
+    # Update the paginator's state based on the current results of the query.
+    def update_offsets(results)
+      paginator.metadata.merge!(offsets: results_offsets(results))
+    end
+
+    def target_record_id
+      return unless paginator.offset
+
+      paginator.metadata[:offsets].key(paginator.offset.to_s).to_s
+    end
+
+    def target_record_id=(record_id)
+      paginator.offset = lookup_offset(record_id)
+      paginator.per_page = 1
+    end
+
+    def results_offsets(results)
+      collection_key = paginator.metadata[:collection_key]
+      results.map.with_index do |record, index|
+        record_id = record.send(collection_key)
+        [record_id.to_s, index.to_s]
+      end.to_h
+    end
+
+    ###
+    # @return [Integer] The offset to use with the CachedResultsQuery to select the given record
+    def lookup_offset(record_id)
+      metadata = paginator.metadata[:offsets]
+      return 0 unless metadata
+
+      stringified_record_id = record_id.to_s
+      # metadata can have symbol keys or string keys, depending on how the cursor was created.
+      offset =  metadata.include?(stringified_record_id) ?
+                  metadata[stringified_record_id] :
+                  metadata[stringified_record_id.to_sym]
+      offset.to_i
+    end
+  end
+end

data/lib/pack_api/models/querying/abstract_boolean_filter.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  class AbstractBooleanFilter < DiscoverableFilter
+    attr_accessor :value
+
+    YES_VALUE = 'Yes'
+    NO_VALUE = 'No'
+    NOT_APPLICABLE_VALUE = ''
+
+    def self.type
+      :tri_state_boolean
+    end
+
+    def self.definition(**)
+      options = [
+        PackAPI::Types::FilterOption.new(label: 'N/A', value: NOT_APPLICABLE_VALUE),
+        PackAPI::Types::FilterOption.new(label: 'Yes', value: YES_VALUE),
+        PackAPI::Types::FilterOption.new(label: 'No', value: NO_VALUE)
+      ]
+
+      PackAPI::Types::BooleanFilterDefinition.new(name: filter_name, type:, options:)
+    end
+
+    def initialize(value:)
+      super()
+      @value = value
+    end
+
+    delegate :present?, to: :value
+
+    def to_h
+      raise NotImplementedError unless self.class.filter_name
+
+      { self.class.filter_name => { value: } }
+    end
+  end
+end

data/lib/pack_api/models/querying/abstract_enum_filter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  class AbstractEnumFilter < DiscoverableFilter
+    attr_accessor :value, :exclude_param
+    validates :exclude_param, inclusion: { in: %w[true false], allow_nil: true, message: 'must be either true or false' }
+
+    def self.type
+      :enum
+    end
+
+    def self.definition(**)
+      PackAPI::Types::EnumFilterDefinition.new(name: filter_name,
+                                      type:,
+                                      options: filter_options(**),
+                                      can_exclude: can_exclude?)
+    end
+
+    def self.filter_options(**)
+      raise NotImplementedError
+    end
+
+    private_class_method :filter_options
+
+    def initialize(value: nil, exclude: nil)
+      super()
+      @present = !value.nil?
+      @value = Array.wrap(value.presence)
+      @exclude_param = exclude
+    end
+
+    def present?
+      @present
+    end
+
+    def exclude?
+      exclude_param.to_s.downcase == 'true'
+    end
+
+    def to_h
+      raise NotImplementedError unless self.class.filter_name
+
+      payload = present? ?
+                  { value: } :
+                  { value: nil }
+      payload[:exclude] = exclude?.to_s if self.class.can_exclude?
+      { self.class.filter_name => payload }
+    end
+
+    def self.can_exclude?
+      true
+    end
+  end
+end

data/lib/pack_api/models/querying/abstract_filter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  class AbstractFilter
+    def present?
+      false
+    end
+
+    ###
+    # Applies the filter to the given query.
+    # @param [ComposableQuery] query the active record relation to apply the filter to
+    def apply_to(query)
+    end
+  end
+end

data/lib/pack_api/models/querying/abstract_numeric_filter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  class AbstractNumericFilter < DiscoverableFilter
+    attr_accessor :operator, :value
+
+    def self.type
+      :numeric
+    end
+
+    def self.definition(**)
+      operators = [
+        PackAPI::Types::FilterOption.new(label: 'Greater than', value: '>'),
+        PackAPI::Types::FilterOption.new(label: 'Greater than or equal to', value: '>='),
+        PackAPI::Types::FilterOption.new(label: 'Equal to', value: '='),
+        PackAPI::Types::FilterOption.new(label: 'Less than or equal to', value: '<='),
+        PackAPI::Types::FilterOption.new(label: 'Less than', value: '<')
+      ]
+
+      PackAPI::Types::NumericFilterDefinition.new(name: filter_name, operators:)
+    end
+
+    def initialize(operator:, value:)
+      super()
+      @operator = operator
+      @value = value
+    end
+
+    delegate :present?, to: :value
+
+    def to_h
+      raise NotImplementedError unless self.class.filter_name
+
+      { self.class.filter_name => { operator:, value: } }
+    end
+  end
+end

data/lib/pack_api/models/querying/abstract_range_filter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  class AbstractRangeFilter < DiscoverableFilter
+    attr_accessor :min_value, :max_value
+
+    def self.type
+      :range
+    end
+
+    def self.definition(**)
+      PackAPI::Types::RangeFilterDefinition.new(name: filter_name)
+    end
+
+    def initialize(min_value:, max_value:)
+      super()
+      @min_value = min_value
+      @max_value = max_value
+    end
+
+    def present?
+      min_value.present? || max_value.present?
+    end
+
+    def to_h
+      raise NotImplementedError unless self.class.filter_name
+
+      { self.class.filter_name => { min_value:, max_value: } }
+    end
+  end
+end