openstax_utilities 4.1.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5f74a54eb979770038bb0b7a22dd9ab49c7d0bd7
-  data.tar.gz: 24be3a1eba292de415db675f55c93fcb127bf693
+SHA256:
+  metadata.gz: fc7366a73ada7f334bd42ca06e41c0043f92e0d2aff08969f5ec1759275b1885
+  data.tar.gz: 86fa1a1dbe2f4c8521afb1b6ce635b63c8c2140e6656de3028887fd22d7872d1
 SHA512:
-  metadata.gz: 3cd0d23114ea4b34234afab28e67ee749af4150a50510fc85c12ec740a10a45518be29405ca8a350ee713eda378850e205394207d3d09ee74ae4c68ab6fac132
-  data.tar.gz: 77855c34ee526501c39e723164036aa2af493cb473fb4f7c68b481795844641ca6170ed8da1f39a5c6b5a15cdd99bd42ebce9b5d7f379823330f2209bc6598e8
+  metadata.gz: 26555b0e6c39c6cc7c3615d6e948849cce15aa9ff67ebafb5fad260ddb408a8003598b2e588f10ea1c2ed55256ade08a223ad92517b8fcc45adfeb8976583322
+  data.tar.gz: c36765470b6f808e37e2145538b49b56312568ea9ddc73f8329c94e7eb593ecaa8fa5bd09f999db6e7deda74a6792a8c85fdfa4bd2e850a63239de85fbaebd4d

data/app/routines/openstax/utilities/limit_and_paginate_relation.rb

@@ -0,0 +1,85 @@
+# Database-agnostic search result limiting and pagination routine
+#
+# Counts the number of items in a relation and empties it
+# if the number exceeds the specified absolute maximum
+# Otherwise, applies the specified pagination
+#
+# Callers of this routine provide the relation argument and
+# may provide the max_items, per_page and page arguments
+#
+# Required arguments:
+#
+#   Developer-supplied:
+#
+#   relation  - the ActiveRecord::Relation to be limited or paginated
+#
+# Optional arguments:
+#
+#   Developer-supplied:
+#
+#   max_items - the maximum allowed number of search results
+#               default: nil (disabled)
+#
+#   User or developer-supplied:
+#
+#   per_page  - the maximum number of search results per page
+#               default: nil (disabled)
+#   page      - the number of the page to return
+#               default: 1
+#
+# This routine's outputs contain:
+#
+#   outputs[:total_count] - the total number of items in the relation
+#   outputs[:items]       - the original relation after it has
+#                           potentially been emptied or paginated
+
+require 'lev'
+
+module OpenStax
+  module Utilities
+    class LimitAndPaginateRelation
+
+      lev_routine transaction: :no_transaction
+
+      protected
+
+      def exec(*args)
+
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        relation = options[:relation] || args[0]
+        max_items = options[:max_items] || nil
+        per_page = Integer(options[:per_page]) rescue nil
+        page = Integer(options[:page]) rescue 1
+
+        raise ArgumentError, 'You must specify a :relation option' \
+          if relation.nil?
+
+        fatal_error(offending_inputs: :per_page,
+                    message: 'Invalid page size',
+                    code: :invalid_per_page) if !per_page.nil? && per_page < 1
+        fatal_error(offending_inputs: :page,
+                    message: 'Invalid page number',
+                    code: :invalid_page) if page < 1
+
+        outputs[:total_count] = relation.count
+
+        if !max_items.nil? && outputs[:total_count] > max_items
+          # Limiting
+          relation = relation.none
+          nonfatal_error(code: :too_many_items,
+                         message: "The number of matches exceeded the allowed limit of #{
+                           max_items} matches. Please refine your query and try again.")
+        elsif per_page.nil?
+          relation = relation.none if page > 1
+        else
+          # Pagination
+          relation = relation.limit(per_page).offset(per_page*(page-1))
+        end
+
+        outputs[:items] = relation
+      end
+
+    end
+
+  end
+end

data/app/routines/openstax/utilities/order_relation.rb

@@ -0,0 +1,105 @@
+# Database-agnostic search result ordering routine
+#
+# Performs ordering of search results
+#
+# Callers of this routine provide the relation,
+# sortable_fields and order_by arguments
+#
+# Required arguments:
+#
+#   Developer-supplied:
+#
+#   relation        - the ActiveRecord::Relation to be ordered
+#
+#   sortable_fields - list of fields that can appear in the order_by argument
+#                     can be a Hash that maps field names to database columns
+#                     or an Array of Strings
+#                     invalid fields in order_by will be replaced with
+#                     the first field listed here, in :asc order
+#
+# Optional arguments:
+#
+#   User or developer-supplied:
+#
+#   order_by        - list of fields to order by, with optional sort directions
+#                     can be (an Array of) Hashes, or Strings
+#                     default: {sortable_fields.values.first => :asc}
+#
+# This routine's outputs contain:
+#
+#   outputs[:items] - a relation containing the ordered records
+
+require 'lev'
+
+module OpenStax
+  module Utilities
+    class OrderRelation
+
+      lev_routine transaction: :no_transaction
+
+      protected
+
+      def exec(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        relation = options[:relation] || args[0]
+        sortable_fields = options[:sortable_fields] || args[1]
+        order_by = options[:order_by] || args[2]
+
+        raise ArgumentError, 'You must specify a :relation option' \
+          if relation.nil?
+        raise ArgumentError, 'You must specify a :sortable_fields option' \
+          if sortable_fields.nil?
+
+        # Convert sortable_fields to Hash if it's an Array
+        sortable_fields = Hash[*sortable_fields.collect{|s| [s.to_s, s]}] \
+          if sortable_fields.is_a? Array
+
+        # Ordering
+        order_bys = sanitize_order_bys(sortable_fields, order_by)
+        outputs[:items] = relation.order(order_bys)
+      end
+
+      # Returns an order_by Object
+      def sanitize_order_by(sortable_fields, field = nil, dir = nil)
+        sanitized_field = sortable_fields[field.to_s.downcase] || \
+                            sortable_fields.values.first
+        sanitized_dir = dir.to_s.downcase == 'desc' ? :desc : :asc
+        case sanitized_field
+        when Symbol
+          {sanitized_field => sanitized_dir}
+        when Arel::Attributes::Attribute
+          sanitized_field.send sanitized_dir
+        else
+          "#{sanitized_field.to_s} #{sanitized_dir.to_s.upcase}"
+        end
+      end
+
+      # Returns an Array of order_by Objects
+      def sanitize_order_bys(sortable_fields, order_bys = nil)
+        obs = case order_bys
+        when Array
+          order_bys.collect do |ob|
+            case ob
+            when Hash
+              sanitize_order_by(sortable_fields, ob.keys.first, ob.values.first)
+            when Array
+              sanitize_order_by(sortable_fields, ob.first, ob.second)
+            else
+              sanitize_order_by(sortable_fields, ob)
+            end
+          end
+        when Hash
+          order_bys.collect { |k, v| sanitize_order_by(sortable_fields, k, v) }
+        else
+          order_bys.to_s.split(',').collect do |ob|
+            fd = ob.split(' ')
+            sanitize_order_by(sortable_fields, fd.first, fd.second)
+          end
+        end
+        obs.blank? ? sanitize_order_by(sortable_fields) : obs
+      end
+
+    end
+
+  end
+end

data/app/routines/openstax/utilities/search_and_organize_relation.rb

@@ -0,0 +1,130 @@
+# Database-agnostic routine for keyword searching
+# and ordering, limiting and paginating search results
+#
+# Searches, orders, imposes a maximum number or records and paginates
+# a given relation using the appropriate routines and user-supplied
+# parameters from the params hash
+#
+# See the search_routine.rb, order_routine.rb and
+# limit_and_paginate_routine.rb files for more information
+#
+# Callers must provide the search_relation, search_proc and
+# sortable_fields arguments and may provide the max_items argument
+#
+# Users must provide the q (query) argument and may provide
+# the order_by, per_page and page arguments in the params hash
+# Users must also be authorized to search the base class of the search_routine
+#
+# Required arguments:
+#
+#   Developer-supplied:
+#
+#   relation        - the initial ActiveRecord::Relation to start searching on
+#   search_proc     - a Proc passed to keyword_search's `search` method
+#                     it receives keyword_search's `with` object as argument
+#                     this proc must define the `keyword` blocks for keyword_search
+#                     the relation to be scoped is contained in the @items instance variable
+#                     the `to_string_array` helper can help with
+#                     parsing strings from the query
+#
+#   sortable_fields - list of fields that can appear in the order_by argument
+#                     can be a Hash that maps field names to database columns
+#                     or an Array of Strings
+#                     invalid fields in order_by will be replaced with
+#                     the first field listed here, in :asc order
+#
+#   User or UI-supplied:
+#
+#   params[:query]  - a String that follows the keyword format
+#                     Keywords have the format keyword:value
+#                     Keywords can also be negated with -, as in -keyword:value
+#                     Values are comma-separated; keywords are space-separated
+#
+# Optional arguments:
+#
+#   Developer-supplied (recommended to prevent scraping):
+#
+#   max_items         - the maximum number of matching items allowed to be returned
+#                       no results will be returned if this number is exceeded,
+#                       but the total result count will still be returned
+#                       applies even if pagination is enabled
+#                       default: nil (disabled)
+#
+#   User or UI-supplied:
+#
+#   params[:order_by] - list of fields to order by, with optional sort directions
+#                       can be (an Array of) Hashes, or Strings
+#                       default: {sortable_fields.values.first => :asc}
+#
+#   params[:per_page] - the maximum number of search results per page
+#                       default: nil (disabled)
+#   params[:page]     - the number of the page to return 
+#                       default: 1
+#
+# This handler's output contains:
+#
+#   outputs[:total_count] - the total number of items that matched the query
+#   outputs[:items]       - the relation returned by the search routines
+
+require 'lev'
+
+module OpenStax
+  module Utilities
+    class SearchAndOrganizeRelation
+
+      lev_routine transaction: :no_transaction
+
+      uses_routine SearchRelation,
+                   as: :search
+      uses_routine OrderRelation,
+                   as: :order
+      uses_routine LimitAndPaginateRelation,
+                   as: :limit_and_paginate,
+                   errors_are_fatal: false,
+                   translations: { inputs: { type: :verbatim },
+                                   outputs: { type: :verbatim } }
+
+      protected
+
+      def exec(*args, &search_proc)
+
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        relation = options[:relation] || args[0]
+        sortable_fields = options[:sortable_fields] || args[1]
+        params = options[:params] || args[2]
+        search_proc ||= options[:search_proc] || args[3]
+        max_items = options[:max_items] || nil
+
+        raise ArgumentError, 'You must specify a :relation option' \
+          if relation.nil?
+        raise ArgumentError, 'You must specify a :sortable_fields option' \
+          if sortable_fields.nil?
+        raise ArgumentError, 'You must specify a :params option' if params.nil?
+        raise ArgumentError, 'You must specify a block or :search_proc option' \
+          if search_proc.nil?
+
+        query = params[:query] || params[:q]
+        order_by = params[:order_by] || params[:ob]
+        per_page = params[:per_page] || params[:pp]
+        page = params[:page] || params[:p]
+
+        items = run(:search, relation: relation, search_proc: search_proc,
+                    query: query).outputs[:items]
+
+        items = run(:order, relation: items, sortable_fields: sortable_fields,
+                    order_by: order_by).outputs[:items]
+
+        if max_items.nil? && per_page.nil? && page.nil?
+          outputs[:items] = items
+          outputs[:total_count] = items.count
+          return
+        end
+
+        run(:limit_and_paginate, relation: items, max_items: max_items,
+            per_page: per_page, page: page)
+      end
+
+    end
+
+  end
+end

data/app/routines/openstax/utilities/search_relation.rb

@@ -0,0 +1,94 @@
+# Database-agnostic keyword searching routine
+#
+# Filters a relation based on a search Proc and a query String
+# See https://github.com/bruce/keyword_search for more information
+# about these arguments
+#
+# Callers of this routine provide the search_proc, relation and query arguments
+#
+# Required arguments:
+#
+#   Developer-supplied:
+#
+#   relation    - the initial ActiveRecord::Relation to start searching on
+#   search_proc - a Proc passed to keyword_search's `search` method
+#                 it receives keyword_search's `with` object as argument
+#                 this proc must define the `keyword` blocks for keyword_search
+#                 the relation to be scoped is contained in the @items instance variable
+#                 the `to_string_array` helper can help with
+#                 parsing strings from the query
+#
+#   User or developer-supplied:
+#
+#   query       - a String that follows the keyword format
+#                 Keywords have the format keyword:value
+#                 Keywords can also be negated with -, as in -keyword:value
+#                 Values are comma-separated, while keywords are space-separated
+#
+# This routine's outputs contain:
+#
+#   outputs[:items] - a relation with records that match the query terms
+
+require 'lev'
+require 'keyword_search'
+
+module OpenStax
+  module Utilities
+    class SearchRelation
+
+      lev_routine transaction: :no_transaction
+
+      protected
+
+      def exec(*args, &search_proc)
+
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        @items = options[:relation] || args[0]
+        query = options[:query] || args[1]
+        search_proc ||= options[:search_proc] || args[2]
+
+        raise ArgumentError, 'You must specify a :relation option' if @items.nil?
+        raise ArgumentError, 'You must specify a block or :search_proc option' \
+          if search_proc.nil?
+
+        # Scoping
+
+        begin
+          ::KeywordSearch.search(query.to_s) do |with|
+            instance_exec(with, &search_proc)
+          end
+        rescue KeywordSearch::ParseError
+          fatal_error(code: :invalid_query,
+                      message: 'The search query string provided is invalid')
+        end
+
+        outputs[:items] = @items
+      end
+
+      # Parses a keyword string into an array of strings
+      # User-supplied wildcards are removed and strings are split on commas
+      # Then wildcards are appended or prepended if the append_wildcard or
+      # prepend_wildcard options are specified
+      def to_string_array(str, options = {})
+        sa = case str
+        when Array
+          str.collect{|name| name.gsub('%', '').split(',')}.flatten
+        else
+          str.to_s.gsub('%', '').split(',')
+        end
+        sa = sa.collect{|str| "#{str}%"} if options[:append_wildcard]
+        sa = sa.collect{|str| "%#{str}"} if options[:prepend_wildcard]
+        sa
+      end
+
+      # Parses a keyword string into an array of numbers
+      # User-supplied wildcards are removed and strings are split on commas
+      # Only numbers are returned
+      def to_number_array(str)
+        to_string_array(str).collect{|s| Integer(s) rescue nil}.compact
+      end
+
+    end
+
+  end
+end

data/lib/openstax/utilities/access_policy.rb

@@ -24,7 +24,8 @@ module OpenStax
       end
 
       def self.require_action_allowed!(action, requestor, resource)
-        raise SecurityTransgression unless action_allowed?(action, requestor, resource)
+        msg = "\"#{requestor.inspect}\" is not allowed to perform \"#{action}\" on \"#{resource.inspect}\""
+        raise(SecurityTransgression, msg) unless action_allowed?(action, requestor, resource)
       end
 
       def self.action_allowed?(action, requestor, resource)
@@ -38,7 +39,7 @@ module OpenStax
         end
 
         resource_class = resource.is_a?(Class) ? resource : resource.class
-        policy_class = instance.resource_policy_map[resource_class.to_s]
+        policy_class = instance.resource_policy_map[resource_class.to_s].try(:constantize)
 
         # If there is no policy registered, we by default deny access
         return false if policy_class.nil?
@@ -47,7 +48,7 @@ module OpenStax
       end
 
       def self.register(resource_class, policy_class)
-        self.instance.resource_policy_map[resource_class.to_s] = policy_class
+        self.instance.resource_policy_map[resource_class.to_s] = policy_class.to_s
       end
 
     end