praxis 2.0.pre.11 → 2.0.pre.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bbd374311046cf8d12c68d564382de6cbfd0c1032c45bbc8c1ac00d7a02e68a
-  data.tar.gz: e33676f45266facdbcae595c2c05ca94ae8dfa34134aa9e4113e5a5d9d729052
+  metadata.gz: 2fe1ba3515514e34ad80775b6b68b4fe046fd1806c40d2345c4fa945d34ed92a
+  data.tar.gz: 11934130d0c527d1bc52020f393f2a5167ba3f88c876e81deaf7eaa05c518eff
 SHA512:
-  metadata.gz: 5db86e95bd0b723560036435ded99b893fd92bd55f20dc4b49e326d96e7c9422549124ba986eb3248ff746d6bf928a60e6677b854c8761a34c026c7430a578bb
-  data.tar.gz: 39677f252617f79d3d054fd2286562d3355310d8161096c7c73294d2b242cee4ebdf749b462d7f1c5261fc487e80ba473dcd258dcb77a510c47db7e698275cad
+  metadata.gz: a32c98bd77159e59c5192390c2eb683b62930cb3f4b30cbe680b63db5b0c076199b0fb63e5a0a55abb772a92cadef19a8f05d7cedf7eb8218f585ce8b7a01acf
+  data.tar.gz: 2a086210825ac166730d63b9ea7e5baa2420cdeb1772e434028b95de356ce69778d983fededb1125825f5b036bc0a0c13fc9b61536d77a31cc63cd87f6a48c02

data/.ruby-version

@@ -1 +1 @@
-2.6.3
+2.7.1

data/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## next
 
+## 2.0.pre.16
+
+* Updated `Resource.property` signature to only accept known named arguments (`dependencies` and `though` at this time) to spare anyone else from going insane wondering why their `depednencies` aren't working.
+* Fixed issue with Filtering Params, that occurred with using the ! or !! operators on String-typed fields.
+
+## 2.0.pre.14
+
+* More encoding/decoding robustness for filters. 
+  * Specs for how to encode filters are now properly defined by:
+    * The "value" of the filters query string needs to be URI encoded (like any other query string value). This encoding is subject to the normal rules, and therefore "could" leave some of the URI unreserved characters (i.e., 'markers') unencoded depending on the client (Section 2.2 of https://tools.ietf.org/html/rfc2396).
+    * The "values" for any of the conditions in the contents of the filters, however, will need to be properly "escaped" as well (prior to URL-encoding the whole syntax string itself like described above). This means that any match value needs to ensure that it has (at least) "(",")","|","&" and "," escaped as they are reserved characters for the filter expression syntax. For example, if I want to search for a name with value "Rocket&(Pants)", I need to first compose the syntax by: "name=<escaped Rocket&(Pants)>, which is "name=Rocket%26%28Pants%29" and then, just URI encode that query string value for the filters parameter in the URL like any other. For example: "filters=name%3DRocket%2526%2528Pants%2529"
+    * When using a multi-match (csv-separated) list of values, you need to escape each of the values as well, leaving the 'comma' unescape, as that's part of the syntax. Then uri-encode it all for the filters query string parameter value like above.
+  * Now, one can properly differentiate between fuzzy query prefix/postfix, and the literal data to search for (which can be or include '*'). Report that multi-matches (i.e., csv separated values for a single field, which translate into "IN" clauses) is not allowed if fuzzy matches are received (need to use multiple OR clauses for it).
+
+## 2.0.pre.13
+
+* Fix filters parser regression, which would incorrectly decode url-encoded values
+
+## 2.0.pre.12
+
+* Rebuilt API filters to support a much richer syntax. One can now use ANDs and ORs (with ANDs having order precedence), as well as group them with parenthesis. The same individual filter operands are supported. For example: 'email=*@gmail.com&(friends.first_name=Joe*,Patty|friends.last_name=Smith)
+
 ## 2.0.pre.11
 
 - Remove MapperPlugin's `set_selectors` (made `selector_generator` lazy instead), and ensure it includes the rendering extensions to the Controllers. Less things to configure if you opt into the Mapper way.

data/bin/praxis

@@ -9,6 +9,12 @@ rescue Bundler::GemfileNotFound
   # no-op: we might be installed as a system gem
 end
 
+if ARGV[0] == "version"
+  require 'praxis/version'
+  puts "Praxis version #{Praxis::VERSION}"
+  exit 0
+end
+
 if ["routes","docs","console"].include? ARGV[0]
   require 'rake'
   require 'praxis'

data/lib/praxis/api_definition.rb

@@ -97,8 +97,10 @@ module Praxis
         description( description || 'Standard response for successful HTTP requests.' )
 
         media_type media_type
-        location location
-        headers headers if headers
+        location if location
+        headers&.each do |(name, value)|
+          header(name: name, value: value)
+        end
       end
 
       api.response_template :created do |media_type: nil, location: nil, headers: nil, description: nil|
@@ -106,8 +108,10 @@ module Praxis
         description( description || 'The request has been fulfilled and resulted in a new resource being created.' )
 
         media_type media_type if media_type
-        location location
-        headers headers if headers
+        location if location
+        headers&.each do |(name, value)|
+          header(name: name, value: value)
+        end
       end
     end
 

data/lib/praxis/collection.rb

@@ -32,5 +32,16 @@ module Praxis
       @member_type.domain_model
     end
 
+    def self.json_schema_type
+      :array
+    end
+
+    def self.as_json_schema(**args)
+      the_type = @attribute && @attribute.type || member_type
+      {
+        type: json_schema_type,
+        items: { '$ref': "#/components/schemas/#{the_type.id}" }
+      }
+    end
   end
 end

data/lib/praxis/docs/open_api/response_object.rb

@@ -16,12 +16,27 @@ module Praxis
 
         def dump_response_headers_object( headers )
           headers.each_with_object({}) do |(name,data),accum|
-            # data is a hash with :value and :type keys
-            # How did we say in that must match a value in json schema again??
-            accum[name] = {
-              schema: SchemaObject.new(info: data[:type])
-              # allowed values:  [ data[:value] ] ??? is this the right json schema way?
-            }
+            # each header comes from Praxis::ResponseDefinition 
+            # the keys are the header names, and value can be:
+            #  "true"  => means it only needs to exist
+            #  String => which means that it has to fully match
+            #  Regex  => which means it has to regexp match it
+
+            # Get the schema from the type (defaulting to string in case the type doesn't have the as_json_schema defined)
+            schema = data[:attribute].type.as_json_schema rescue { type: :string }
+            hash = { description: data[:description] || '', schema: schema }
+            # Note, our Headers in response definition are not full types...they're basically only 
+            # strings, which can either match anything, match the exact word or match a regex
+            # they don't even have a description...
+            data_value = data[:value]
+            if data_value.is_a? String
+              hash[:pattern] = "^#{data_value}$" # Exact String match
+            elsif data_value.is_a? Regexp
+              sanitized_pattern = data_value.inspect[1..-2] #inspect returns enclosing '/' characters
+              hash[:pattern] = sanitized_pattern
+            end
+
+            accum[name] = hash
           end
         end
 

data/lib/praxis/extensions/attribute_filtering.rb

@@ -1,2 +1,15 @@
 require 'praxis/extensions/attribute_filtering/filtering_params'
-require 'praxis/extensions/attribute_filtering/filter_tree_node'
+require 'praxis/extensions/attribute_filtering/filter_tree_node'
+module Praxis
+  module Extensions
+    module AttributeFiltering
+      class MultiMatchWithFuzzyNotAllowedByAdapter < StandardError
+        def initialize
+          msg = 'Matching multiple, comma-separated values with fuzzy matches for a single field is not allowed by this DB adapter'\
+                'Please use multiple OR clauses instead.'
+          super(msg)
+        end
+      end
+    end
+  end
+end

data/lib/praxis/extensions/attribute_filtering/active_record_filter_query_builder.rb

@@ -23,14 +23,17 @@ module Praxis
       end
 
       class ActiveRecordFilterQueryBuilder
-      attr_reader :query, :model, :filters_map
+        REFERENCES_STRING_SEPARATOR = '/'
+        attr_reader :model, :filters_map
 
         # Base query to build upon
         def initialize(query: , model:, filters_map:, debug: false)
-          @query = query
+          # Note: Do not make the initial_query an attr reader to make sure we don't count/leak on modifying it. Easier to mostly use class methods
+          @initial_query = query
           @model = model
           @filters_map = filters_map
           @logger = debug ? Logger.new(STDOUT) : nil
+          @active_record_version_maj = ActiveRecord.gem_version.segments[0]
         end
         
         def debug_query(msg, query)
@@ -40,26 +43,103 @@ module Praxis
         def generate(filters)
           # Resolve the names and values first, based on filters_map
           root_node = _convert_to_treenode(filters)
-          craft_filter_query(root_node, for_model: @model)
-          debug_query("SQL due to filters: ", @query.all)
-          @query
+          crafted = craft_filter_query(root_node, for_model: @model)
+          debug_query("SQL due to filters: ", crafted.all)
+          crafted
         end
 
         def craft_filter_query(nodetree, for_model:)
           result = _compute_joins_and_conditions_data(nodetree, model: for_model)
-          @query = query.joins(result[:associations_hash]) unless result[:associations_hash].empty?
+          return @initial_query if result[:conditions].empty?
 
-          result[:conditions].each do |condition|
-            filter_name = condition[:name]
-            filter_value = condition[:value]
+          
+          # Find the root group (usually an AND group) but can be an OR group, or nil if there's only 1 condition
+          root_parent_group = result[:conditions].first[:node_object].parent_group || result[:conditions].first[:node_object]
+          while root_parent_group.parent_group != nil
+            root_parent_group = root_parent_group.parent_group
+          end
+
+          # Process the joins
+          query_with_joins = result[:associations_hash].empty? ? @initial_query : @initial_query.joins(result[:associations_hash])
+
+          # Proc to apply a single condition
+          apply_single_condition = Proc.new do |condition, associated_query|
+            colo = condition[:model].columns_hash[condition[:name].to_s]
             column_prefix = condition[:column_prefix]
+            
+            # Mark where clause referencing the appropriate alias IF it's not the root table, as there is no association to reference
+            # If we added root table as a reference, we better make sure it is not quoted, as it actually makes AR to see it as an 
+            # unmatched reference and eager loads the whole association (it means eager load ALL the things). Not good.
+            unless for_model.table_name == column_prefix
+              associated_query = associated_query.references(build_reference_value(column_prefix, query: associated_query))
+            end
+            self.class.add_clause(
+              query: associated_query, 
+              column_prefix: column_prefix, 
+              column_object: colo, 
+              op: condition[:op], 
+              value: condition[:value],
+              fuzzy: condition[:fuzzy]
+            )
+          end
 
-            colo = condition[:model].columns_hash[filter_name.to_s]
-            add_clause(column_prefix: column_prefix,  column_object: colo, op: condition[:op], value: filter_value)
+          if @active_record_version_maj < 6
+            # ActiveRecord < 6 does not support '.and' so no nested things can be done
+            # But we can still support the case of 1+ flat conditions of the same AND/OR type
+            if root_parent_group.is_a?(FilteringParams::Condition)
+              # A Single condition it is easy to handle
+              apply_single_condition.call(result[:conditions].first, query_with_joins)
+            elsif root_parent_group.items.all?{|i| i.is_a?(FilteringParams::Condition)}
+              # Only 1 top level root, with only with simple condition items
+              if root_parent_group.type == :and
+                result[:conditions].reverse.inject(query_with_joins) do |accum, condition|
+                  apply_single_condition.call(condition, accum)
+                end
+              else
+                # To do a flat OR, we need to apply the first condition to the incoming query
+                # and then apply any extra ORs to it. Otherwise Book.or(X).or(X) still matches all books
+                cond1, *rest = result[:conditions].reverse
+                start_query = apply_single_condition.call(cond1, query_with_joins)
+                rest.inject(start_query) do |accum, condition|
+                  accum.or(apply_single_condition.call(condition, query_with_joins))
+                end
+              end
+            else
+              raise "Mixing AND and OR conditions is not supported for ActiveRecord <6."
+            end
+          else #  ActiveRecord 6+
+            # Process the conditions in a depth-first order, and return the resulting query
+            _depth_first_traversal(
+              root_query: query_with_joins, 
+              root_node: root_parent_group, 
+              conditions: result[:conditions], 
+              &apply_single_condition
+            )
           end
         end
 
         private
+        def _depth_first_traversal(root_query:, root_node:, conditions:, &block)
+          # Save the associated query for non-leaves 
+          root_node.associated_query = root_query if root_node.is_a?(FilteringParams::ConditionGroup)
+          
+          if root_node.is_a?(FilteringParams::Condition)
+            matching_condition = conditions.find {|cond| cond[:node_object] == root_node }
+
+            # The simplified case of a single top level condition (without a wrapping group)
+            # will need to pass the root query itself
+            associated_query = root_node.parent_group ? root_node.parent_group.associated_query : root_query
+            return yield matching_condition, associated_query
+          else
+            first_query, *rest_queries = root_node.items.map do |child|
+              _depth_first_traversal(root_query: root_query, root_node: child, conditions: conditions, &block)
+            end
+
+            rest_queries.each.inject(first_query) do |q, a_query|
+              root_node.type == :and ? q.and(a_query) : q.or(a_query)
+            end
+          end
+        end
 
         def _mapped_filter(name)
           target = @filters_map[name]
@@ -89,7 +169,9 @@ module Praxis
               if mapped_value.is_a?(Proc)
                 result = mapped_value.call(filter)
                 # Result could be an array of hashes (each hash has name/op/value to identify a condition)
-                result.is_a?(Array) ? result : [result]
+                result_from_proc = result.is_a?(Array) ? result : [result]
+                # Make sure we tack on the node object associated with the filter
+                result_from_proc.map{|hash| hash.merge(node_object: filter[:node_object])}
               else
                 # For non-procs there's only 1 filter and 1 value (we're just overriding the mapped value)
                 [filter.merge( name: mapped_value)]
@@ -109,59 +191,58 @@ module Praxis
             h[name] = result[:associations_hash] 
             conditions += result[:conditions]
           end
-          column_prefix = nodetree.path == [ALIAS_TABLE_PREFIX] ? model.table_name : nodetree.path.join('/')
-          #column_prefix = nodetree.path == [ALIAS_TABLE_PREFIX] ? nil : nodetree.path.join('/')
+          column_prefix = nodetree.path == [ALIAS_TABLE_PREFIX] ? model.table_name : nodetree.path.join(REFERENCES_STRING_SEPARATOR)
           nodetree.conditions.each do |condition|
             conditions += [condition.merge(column_prefix: column_prefix, model: model)]
           end
           {associations_hash: h, conditions: conditions}
         end
 
-        def add_clause(column_prefix:, column_object:, op:, value:)
-          @query = @query.references(build_reference_value(column_prefix)) #Mark where clause referencing the appropriate alias
-          likeval = get_like_value(value)
+        def self.add_clause(query:, column_prefix:, column_object:, op:, value:,fuzzy:)
+          likeval = get_like_value(value,fuzzy)
           case op
-            when '!' # name! means => name IS NOT NULL (and the incoming value is nil)
-              op = '!='
-              value = nil # Enforce it is indeed nil (should be)
-            when '!!'
-              op = '='
-              value = nil # Enforce it is indeed nil (should be)
+          when '!' # name! means => name IS NOT NULL (and the incoming value is nil)
+            op = '!='
+            value = nil # Enforce it is indeed nil (should be)
+          when '!!'
+            op = '='
+            value = nil # Enforce it is indeed nil (should be)
+          end
+
+          case op
+          when '='
+            if likeval
+              add_safe_where(query: query, tab: column_prefix, col: column_object, op: 'LIKE', value: likeval)
+            else
+              quoted_right = quote_right_part(query: query, value: value, column_object: column_object, negative: false)
+              query.where("#{quote_column_path(query: query, prefix: column_prefix, column_object: column_object)} #{quoted_right}")
+            end
+          when '!='
+            if likeval
+              add_safe_where(query: query, tab: column_prefix, col: column_object, op: 'NOT LIKE', value: likeval)
+            else
+              quoted_right = quote_right_part(query: query, value: value, column_object: column_object, negative: true)
+              query.where("#{quote_column_path(query: query, prefix: column_prefix, column_object: column_object)} #{quoted_right}")
             end
-          @query =  case op
-                    when '='
-                      if likeval
-                        add_safe_where(tab: column_prefix, col: column_object, op: 'LIKE', value: likeval)
-                      else
-                        quoted_right = quote_right_part(value: value, column_object: column_object, negative: false)
-                        query.where("#{quote_column_path(column_prefix, column_object)} #{quoted_right}")
-                      end
-                    when '!='
-                      if likeval
-                        add_safe_where(tab: column_prefix, col: column_object, op: 'NOT LIKE', value: likeval)
-                      else
-                        quoted_right = quote_right_part(value: value, column_object: column_object, negative: true)
-                        query.where("#{quote_column_path(column_prefix, column_object)} #{quoted_right}")
-                      end
-                    when '>'
-                      add_safe_where(tab: column_prefix, col: column_object, op: '>', value: value)
-                    when '<'
-                      add_safe_where(tab: column_prefix, col: column_object, op: '<', value: value)
-                    when '>='
-                      add_safe_where(tab: column_prefix, col: column_object, op: '>=', value: value)
-                    when '<='
-                      add_safe_where(tab: column_prefix, col: column_object, op: '<=', value: value)
-                    else
-                      raise "Unsupported Operator!!! #{op}"
-                    end
-        end
-
-        def add_safe_where(tab:, col:, op:, value:)
+          when '>'
+            add_safe_where(query: query, tab: column_prefix, col: column_object, op: '>', value: value)
+          when '<'
+            add_safe_where(query: query, tab: column_prefix, col: column_object, op: '<', value: value)
+          when '>='
+            add_safe_where(query: query, tab: column_prefix, col: column_object, op: '>=', value: value)
+          when '<='
+            add_safe_where(query: query, tab: column_prefix, col: column_object, op: '<=', value: value)
+          else
+            raise "Unsupported Operator!!! #{op}"
+          end
+        end
+
+        def self.add_safe_where(query:, tab:, col:, op:, value:)
           quoted_value = query.connection.quote_default_expression(value,col)
-          query.where("#{quote_column_path(tab, col)} #{op} #{quoted_value}")
+          query.where("#{self.quote_column_path(query: query, prefix: tab, column_object: col)} #{op} #{quoted_value}")
         end
 
-        def quote_column_path(prefix, column_object)
+        def self.quote_column_path(query:, prefix:, column_object:)
           c = query.connection
           quoted_column = c.quote_column_name(column_object.name)
           if prefix
@@ -172,7 +253,7 @@ module Praxis
           end
         end
 
-        def quote_right_part(value:, column_object:, negative:)
+        def self.quote_right_part(query:, value:, column_object:, negative:)
           conn = query.connection
           if value.nil?
             no = negative ? ' NOT' : ''
@@ -190,12 +271,22 @@ module Praxis
         end
 
         # Returns nil if the value was not a fuzzzy pattern
-        def get_like_value(value)
-          if value.is_a?(String) && (value[-1] == '*' || value[0] == '*')
-            likeval = value.dup
-            likeval[-1] = '%' if value[-1] == '*'
-            likeval[0] = '%' if value[0] == '*'
-            likeval
+        def self.get_like_value(value,fuzzy)
+          is_fuzzy = fuzzy.is_a?(Array) ? !fuzzy.compact.empty? : fuzzy
+          if is_fuzzy
+            unless value.is_a?(String)
+              raise MultiMatchWithFuzzyNotAllowedByAdapter.new
+            end
+            case fuzzy
+            when :start_end
+              '%'+value+'%'
+            when :start
+              '%'+value
+            when :end
+              value+'%'
+            end
+          else
+            nil
           end
         end
 
@@ -203,14 +294,14 @@ module Praxis
         maj, min, _ = ActiveRecord.gem_version.segments
         if maj == 5 || (maj == 6 && min == 0)
           # In AR 6 (and 6.0) the references are simple strings
-          def build_reference_value(column_prefix)
+          def build_reference_value(column_prefix, query: nil)
             column_prefix
           end
         else
           # The latest AR versions discard passing references to joins when they're not SqlLiterals ... so let's wrap it
           # with our class, so that it is a literal (already quoted), but that can still provide the expected "symbol" without quotes
           # so that our aliasing code can match it.
-          def build_reference_value(column_prefix)
+          def build_reference_value(column_prefix, query:)
             QuasiSqlLiteral.new(quoted: query.connection.quote_table_name(column_prefix), symbolized: column_prefix.to_sym)
           end
         end