praxis 2.0.pre.2 → 2.0.pre.7

data/lib/praxis/extensions/pagination.rb

@@ -0,0 +1,130 @@
+begin
+  require 'link_header'
+rescue LoadError
+  warn "Praxis::Pagination requires the 'link_header' gem, which can not be found. " \
+       "Please make sure it's in your Gemfile or installed in your system."
+end
+require 'praxis/extensions/pagination/pagination_params'
+require 'praxis/extensions/pagination/ordering_params'
+require 'praxis/extensions/pagination/pagination_handler'
+require 'praxis/extensions/pagination/header_generator'
+
+module Praxis
+  module Extensions
+    module Pagination
+      extend ActiveSupport::Concern
+      # This PaginatedController concern should be added to controllers that have actions that define the
+      # pagination and order parameters so that calling `paginate( query: <base_query>, table: <main_table_name> )`
+      # would handle all the required logic for paginating, ordering and generating the Link and TotalCount headers.
+      # This assumes that the query object are chainable and based on ActiveRecord at the moment (although that logic)
+      # can be easily applied to other chainable query proxies.
+      #
+      # Here's a simple example on how to use it for a fake Items controller
+      # class Items < V1::Controllers::BaseController
+      #   include Praxis::Controller
+      #   include Praxis::Extensions::Rendering
+      #   implements V1::Endpoints::Items
+      #
+      #   include Praxis::Extensions::Pagination
+      #
+      #   def index(filters: nil, pagination: nil, order: nil,  **_args)
+      #     items = current_user.items.all
+      #     items = handle_pagination( query: items)
+      #
+      #     display(items)
+      #   end
+      # end
+      #
+      # This code will properly add the right clauses to the final query based on the pagination strategy and ordering
+      # and it will also generate the Link header with the appropriate relationships depending on the paging strategy.
+      # When total_count is requested in the pagination a header with TotalCount will also be included.
+
+      PaginationStruct = Struct.new(:paginator, :order, :total_count)
+
+      included do
+        after :action do |controller, _callee|
+          if controller.response.status < 300
+            # If this action has the pagination parameter defined,
+            # calculate and set the pagination headers (Link header and possibly Total-Count)
+            if controller._pagination.paginator
+              headers = controller.build_pagination_headers(
+                pagination: controller._pagination,
+                current_url: controller.request.path,
+                current_query_params: controller.request.query
+              )
+              controller.response.headers.merge! headers
+            end
+          end
+        end
+      end
+
+      # Will set the typed paginator and order object into a controller ivar
+      # This is lazily evaluated and memoized, so there's no need to only calculate things for actions that paginate/sort
+      def _pagination
+        return @_pagination if @_pagination
+
+        pagination = {}
+        attrs = request.action&.params&.type&.attributes
+        pagination[:paginator] = request.params.pagination if attrs&.key? :pagination
+        pagination[:order] = request.params.order if attrs&.key? :order
+
+        @_pagination = PaginationStruct.new(pagination[:paginator], pagination[:order])
+      end
+
+      # Main entrypoint: Handles all pagination pieces
+      # takes:
+      # * the query to build from and the table
+      # * the request (for link header generation)
+      # * requires the _pagination variable to be there (set by this module) to return the pagination struct
+      def handle_pagination(query:, type: :active_record)
+        handler_klass = \
+          case type
+          when :active_record
+            ActiveRecordPaginationHandler
+          when :sequel
+            SequelPaginationHandler
+          else
+            raise "Attempting to use pagination but Active Record or Sequel gems found"
+          end
+ 
+        # Gather and save the count if required
+        if _pagination.paginator&.total_count
+          _pagination.total_count = handler_klass.count(query.dup)
+        end
+        
+        query = handler_klass.order(query, _pagination.order)
+        # Maybe this is a class instance instead of a class method?...(of the appropriate AR/Sequel type)...
+        # self.class.paginate(query, table, _pagination)
+        handler_klass.paginate(query, _pagination)
+      end
+
+      def build_pagination_headers(pagination:, current_url:, current_query_params:)
+        links = if pagination.paginator.by
+                  # We're assuming that the last element has a "symbol/string" field with the same name of the "by" pagination.
+                  last_element = response.body.last
+                  if last_element
+                    last_value = last_element[pagination.paginator.by.to_sym] || last_element[pagination.paginator.by]
+                  end
+                  HeaderGenerator.build_cursor_headers(
+                    paginator: pagination.paginator,
+                    last_value: last_value,
+                    total_count: pagination.total_count
+                  )
+                else
+                  HeaderGenerator.build_paging_headers(
+                    paginator: pagination.paginator,
+                    total_count: pagination.total_count
+                  )
+                end
+
+        HeaderGenerator.generate_headers(
+          links: links,
+          current_url: current_url,
+          current_query_params: current_query_params,
+          total_count: pagination.total_count
+        )
+      end
+
+    end
+  end
+end

data/lib/praxis/extensions/pagination/active_record_pagination_handler.rb

@@ -0,0 +1,42 @@
+require_relative 'pagination_handler'
+
+module Praxis
+  module Extensions
+    module Pagination
+      class ActiveRecordPaginationHandler < PaginationHandler
+
+        def self.where_lt(query, attr, value)
+          # TODO: common for AR/Sequel? Seems we could use Arel and more-specific Sequel things
+          query.where(query.table[attr].lt(value))
+        end
+        
+        def self.where_gt(query, attr, value)
+          query.where(query.table[attr].gt(value))
+        end
+
+        def self.order(query, order)
+          return query unless order
+          query = query.reorder('')
+          
+          order.each do |spec_hash|
+            direction, name = spec_hash.first
+            query = query.order(name => direction)
+          end
+          query
+        end
+        
+        def self.count(query)
+          query.count(:all)
+        end
+
+        def self.offset(query, offset)
+          query.offset(offset)
+        end
+
+        def self.limit(query, limit)
+          query.limit(limit)
+        end
+      end
+    end
+  end
+end

data/lib/praxis/extensions/pagination/header_generator.rb

@@ -0,0 +1,70 @@
+module Praxis
+  module Extensions
+    module Pagination
+      class HeaderGenerator        
+        def self.build_cursor_headers(paginator:, last_value:, total_count: nil)
+          [:next, :prev, :first, :last].each_with_object({}) do |rel_name, info|
+            case rel_name
+            when :next
+              # If we don't know the total, we'll try to go to the next page
+              # but assume we're done if there isn't a last value...
+              if last_value
+                info[:next] = { by: paginator.by, from: last_value, items: paginator.items }
+                info[:next][:total_count] = true if total_count.present?
+              end
+            when :prev
+            # Not possible to go back
+            when :first
+              info[:first] = { by: paginator.by, items: paginator.items }
+              info[:first][:total_count] = true if total_count.present?
+            when :last
+              # Not possible to scroll to last
+            end
+          end
+        end
+
+        # This is only for plain paging
+        def self.build_paging_headers(paginator:, total_count: nil)
+          last_page = total_count.nil? ? nil : (total_count / (paginator.items * 1.0)).ceil
+          [:next, :prev, :first, :last].each_with_object({}) do |rel_name, info|
+            num = case rel_name
+                  when :first
+                    1
+                  when :prev
+                    next if paginator.page < 2
+                    paginator.page - 1
+                  when :next
+                    # don't include this link if we know the total and we see there are no more pages
+                    next if last_page.present? && (paginator.page >= last_page)
+                    # if we don't know the total, we'll specify to the next page even if it ends up being blank
+                    paginator.page + 1
+                  when :last
+                    next if last_page.blank?
+                    last_page
+                  end
+            info[rel_name] = {
+              page:         num,
+              items:        paginator.items,
+              total_count:  total_count.present?
+            }
+          end
+        end
+
+        def self.generate_headers(links:, current_url:, current_query_params:, total_count:)
+          mapped = links.map do |(rel, info)|
+            # Make sure to encode it our way (with comma-separated args, as it is our own syntax, and not a query string one)
+            pagination_param = info.map { |(k, v)| "#{k}=#{v}" }.join(",")
+            new_url = current_url + "?" + current_query_params.dup.merge(pagination:  pagination_param).to_query
+
+            LinkHeader::Link.new(new_url, [["rel", rel.to_s]])
+          end
+          link_header = LinkHeader.new(mapped)
+
+          headers = { "Link" => link_header.to_s }
+          headers["Total-Count"] = total_count if total_count
+          headers
+        end
+      end
+    end
+  end
+end

data/lib/praxis/extensions/pagination/ordering_params.rb

@@ -0,0 +1,234 @@
+require 'forwardable'
+
+module Praxis
+  module Extensions
+    module Pagination
+      class OrderingParams
+        include Attributor::Type
+        include Attributor::Dumpable
+        extend Forwardable
+
+        def_delegators :items, :empty?
+
+        # DSL for restricting how to order.
+        # It allows the concrete list of the fields one can use (through 'by_fields')
+        # It also allows to enforce that list for all positions of the ordering definition (through 'enforce_for :all|:first')
+        #  By default, only the first ordering position will be subject to that enforcement (i.e., 'enforce_for :first' is the default)
+        # Example
+        #
+        # attribute :order, Praxis::Types::OrderingParams.for(MediaTypes::Bar) do
+        #   by_fields :id, :name
+        #   enforce_for :all
+        # end
+        class DSLCompiler < Attributor::DSLCompiler
+          def by_fields(*fields)
+            requested = fields.map(&:to_sym)
+            non_matching = requested - target.media_type.attributes.keys
+            unless non_matching.empty?
+              raise "Error, you've requested to order by fields that do not exist in the mediatype!\n" \
+              "The following #{non_matching.size} field/s do not exist in media type #{target.media_type.name} :\n" +
+                    non_matching.join(',').to_s
+            end
+            target.fields_allowed = requested
+          end
+
+          def enforce_for(which)
+            case which.to_sym
+            when :all
+              target.enforce_all = true
+            when :first
+              # nothing, that's the default
+            else
+              raise "Error: unknown parameter for the 'enforce_for' : #{which}. Only :all or :first are allowed"
+            end
+          end
+        end
+
+        # Configurable DEFAULTS
+        @enforce_all_fields = false
+
+        def self.enforce_all_fields(newval = nil)
+          newval ? @enforce_all_fields = newval : @enforce_all_fields
+        end
+
+        # Ordering type that allows you to specify the ordering characteristing of a requested listing
+        # Ordering is based on given mediatype, which allows for ensuring validation of type names etc.
+
+        # Syntax (similar to json-api)
+        # * One can specify ordering based on several fields (to resolve tie breakers) by separating them with commas
+        # * Requesting a descending order can be done by adding a `-` before the field name. Prepending a `+` enforces
+        #   ascending order (which is the default if no sign is specified)
+        # Example:
+        # `name,last_name,-birth_date`
+
+        # Abstract class, which needs to be used by subclassing it through the .for method, to link it to a particular
+        # MediaType, so that the field name checking and value coercion can be performed
+        class << self
+          attr_reader :media_type
+          attr_accessor :fields_allowed
+          attr_accessor :enforce_all # True when we need to enforce the allowed fields at all ordering positions
+
+          def for(media_type, **_opts)
+            unless media_type < Praxis::MediaType
+              raise ArgumentError, "Invalid type: #{media_type.name} for Ordering. " \
+                "Must be a subclass of MediaType"
+            end
+
+            ::Class.new(self) do
+              @media_type = media_type
+              if media_type
+                # By default all fields in the mediatype are allowed (but defining a DSL block will override it to more specific ones)
+                @fields_allowed = media_type.attributes.keys
+              end
+              # Default is to only enforce the allowed fields in the first ordering position (the one typicall uses an index if there)
+              @enforce_all = OrderingParams.enforce_all_fields
+            end
+          end
+        end
+
+        attr_reader :items
+
+        def self.native_type
+          self
+        end
+
+        def self.name
+          'Praxis::Types::OrderingParams'
+        end
+
+        def self.display_name
+          'Ordering'
+        end
+
+        def self.family
+          'string'
+        end
+
+        def self.constructable?
+          true
+        end
+
+        def self.construct(pagination_definition, **options)
+          return self if pagination_definition.nil?
+
+          DSLCompiler.new(self, options).parse(*pagination_definition)
+          self
+        end
+
+        def self.example(_context = Attributor::DEFAULT_ROOT_CONTEXT, **_options)
+          fields = if media_type
+                    chosen_set = if enforce_all
+                                    fields_allowed.sample(2)
+                                  else
+                                    starting_set = fields_allowed.sample(1)
+                                    simple_attrs = media_type.attributes.select do |_k, attr|
+                                      attr.type == Attributor::String || attr.type < Attributor::Numeric || attr.type < Attributor::Temporal
+                                    end.keys
+                                    starting_set + simple_attrs.select { |attr| attr != starting_set.first }.sample(1)
+                                  end
+                    chosen_set.each_with_object([]) do |chosen, arr|
+                      sign = rand(10) < 5 ? "-" : ""
+                      arr << "#{sign}#{chosen}"
+                    end.join(',')
+                  else
+                    "name,last_name,-birth_date"
+                  end
+          load(fields)
+        end
+
+        def self.validate(value, context = Attributor::DEFAULT_ROOT_CONTEXT, _attribute = nil)
+          instance = load(value, context)
+          instance.validate(context)
+        end
+
+        def self.load(order, _context = Attributor::DEFAULT_ROOT_CONTEXT, **_options)
+          return order if order.is_a?(native_type)
+
+          parsed_order = {}
+          unless order.nil?
+            parsed_order = order.split(',').each_with_object([]) do |order_string, arr|
+              item = if order_string[0] == '-'
+                      { desc: order_string[1..-1].to_s }
+                    elsif order_string[0] == '+'
+                      { asc: order_string[1..-1].to_s }
+                    else
+                      { asc: order_string.to_s }
+                    end
+              arr.push item
+            end
+          end
+
+          new(parsed_order)
+        end
+
+        def self.dump(value, **_opts)
+          load(value).dump
+        end
+
+        def self.describe(_root = false, example: nil)
+          hash = super
+
+          if fields_allowed
+            hash[:fields_allowed] = fields_allowed
+            hash[:enforced_for] = enforce_all ? :all : :first
+          end
+
+          hash
+        end
+
+        def initialize(parsed)
+          @items = parsed
+        end
+
+        def validate(_context = Attributor::DEFAULT_ROOT_CONTEXT)
+          return [] if items.blank?
+
+          errors = []
+          if self.class.fields_allowed
+            # Validate against the enforced components (either all, or just the first one)
+            enforceable_items = self.class.enforce_all ? items : [items.first]
+
+            enforceable_items.each do |spec|
+              _dir, field = spec.first
+              field = field.to_sym
+              next unless !self.class.fields_allowed.include?(field)
+              errors << if self.class.media_type.attributes.key?(field)
+                          "Ordering by field \'#{field}\' is disallowed. Ordering is only allowed using the following fields: " +
+                          self.class.fields_allowed.map { |f| "\'#{f}\'" }.join(', ').to_s
+                        else
+                          "Ordering by field \'#{field}\' is not possible as this field does not exist in " \
+                          "media type #{self.class.media_type.name}"
+                        end
+            end
+          end
+
+          errors
+        end
+
+        def dump
+          items.each_with_object([]) do |spec, arr|
+            dir, field = spec.first
+            arr << if dir == :desc
+                    "-#{field}"
+                  else
+                    field
+                  end
+          end.join(',')
+        end
+
+        def each
+          items.each do |item|
+            yield item
+          end
+        end
+      end
+    end
+  end
+end
+
+# Alias it to a much shorter and sweeter name in the Types namespace.
+module Praxis
+  module Types
+    OrderingParams = Praxis::Extensions::Pagination::OrderingParams
+  end
+end