praxis 2.0.pre.13 → 2.0.pre.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4be08481cbad0604fdb8e45dfc66aec895478a0b7578544b773af7fa6f3863f
-  data.tar.gz: 122625c252f5d9a2166e8958408bedf7ac5aee13500488e44c453ddeff3fbcc8
+  metadata.gz: dafcffa2e0d146f5b601ed796cb482c5068482757fc2f88770783536da52ad7e
+  data.tar.gz: c6f8875641b0e418128dd8f8a923a3df639b1a409e65976472c24b6fac52f90e
 SHA512:
-  metadata.gz: 6472e4ef1f9ad601ed5c13774a336b93d52356a3a0bccb3a3707953658918a79457d314ceca1ce676a15f51c10bcebb4556388c95ba3aeca2cbec40625b13734
-  data.tar.gz: d8a4bad9469579530974d3c61d61fd7441b4e9d48d2ecb90ac81d4951cda0293428f750011e406e755103abb162b4fb1c60b87a584fe77da74c68dafaa997ecd
+  metadata.gz: 4728bf36f52fd0bf1f73c9efe02190cde40308be2378232897570deab1aa9e5fcbd1ca2b4335b9ad168c4eedda18143a512512e6c132d851b6f6c9447e891d19
+  data.tar.gz: 1d689d714604b4841f4059b1ef9734f1ceae0a9afcc7e7d75286be28f67cfe2a51cb86fafdd6c66b2ac40acc72bd431c12ad1b33aa91990ceecd690abc9e01ad

data/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## next
 
+## 2.0.pre.17
+* Changed the Parameter Filtering to use left outer joins (and extra conditions), to allow for the proper results when OR clauses are involved in certain configurations.
+* Built support for allowing filtering directly on associations using `!` and `!!` operators. This allows to filter results where 
+there are no associated rows (`!!`) or if there are some associated rows (`!`)
+* Allow implicit definition of `filters_mapping` for filter names that match top-level associations of the model (i.e., like we do for the columns)
+## 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

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,7 +23,8 @@ module Praxis
       end
 
       class ActiveRecordFilterQueryBuilder
-      attr_reader :model, :filters_map
+        REFERENCES_STRING_SEPARATOR = '/'
+        attr_reader :model, :filters_map
 
         # Base query to build upon
         def initialize(query: , model:, filters_map:, debug: false)
@@ -48,9 +49,8 @@ module Praxis
         end
 
         def craft_filter_query(nodetree, for_model:)
-          result = _compute_joins_and_conditions_data(nodetree, model: for_model)
+          result = _compute_joins_and_conditions_data(nodetree, model: for_model, parent_reflection: nil)
           return @initial_query if result[:conditions].empty?
-
           
           # 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]
@@ -59,20 +59,35 @@ module Praxis
           end
 
           # Process the joins
-          query_with_joins = result[:associations_hash].empty? ? @initial_query : @initial_query.joins(result[:associations_hash])
+          query_with_joins = result[:associations_hash].empty? ? @initial_query : @initial_query.left_outer_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
-            associated_query = associated_query.references(build_reference_value(column_prefix, query: associated_query))
+            association_key_column = \
+              if ref = condition[:parent_reflection]
+                # get the target model of the association(where the assoc pk is)
+                target_model = condition[:parent_reflection].klass
+                target_model.columns_hash[condition[:parent_reflection].association_primary_key]
+              else
+                nil
+              end
+
+            # 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]
+              value: condition[:value],
+              fuzzy: condition[:fuzzy],
+              association_key_column: association_key_column,
             )
           end
 
@@ -137,7 +152,8 @@ module Praxis
         def _mapped_filter(name)
           target = @filters_map[name]
           unless target
-            if @model.attribute_names.include?(name.to_s)
+            filter_name = name.to_s
+            if (@model.attribute_names + @model.reflections.keys).include?(filter_name)
               # Cache it in the filters mapping (to avoid later lookups), and return it.
               @filters_map[name] = name
               target = name
@@ -175,32 +191,64 @@ module Praxis
         end
 
         # Calculate join tree and conditions array for the nodetree object and its children
-        def _compute_joins_and_conditions_data(nodetree, model:)
+        def _compute_joins_and_conditions_data(nodetree, model:, parent_reflection:)
           h = {}
           conditions = []
           nodetree.children.each do |name, child|
-            child_model = model.reflections[name.to_s].klass
-            result = _compute_joins_and_conditions_data(child, model: child_model)
-            h[name] = result[:associations_hash] 
+            child_reflection = model.reflections[name.to_s]
+            result = _compute_joins_and_conditions_data(child, model: child_reflection.klass, parent_reflection: child_reflection)
+            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)]
+            # If it's a final ! or !! operation on an association from the parent, it means we need to add a condition
+            # on the existence (or lack of) of the whole associated table
+            ref = model.reflections[condition[:name].to_s]
+            if ref && ['!','!!'].include?(condition[:op])
+              cp = (nodetree.path + [condition[:name].to_s]).join(REFERENCES_STRING_SEPARATOR)
+              conditions += [condition.merge(column_prefix: cp, model: model, parent_reflection: ref)]
+              h[condition[:name]] = {}
+            else
+              # Save the parent reflection where the condition applies as well (used later to get assoc keys)
+              conditions += [condition.merge(column_prefix: column_prefix, model: model, parent_reflection: parent_reflection)]
+            end
+            
           end
           {associations_hash: h, conditions: conditions}
         end
 
-        def self.add_clause(query:, column_prefix:, column_object:, op:, value:)
-          likeval = get_like_value(value)
+        def self.add_clause(query:, column_prefix:, column_object:, op:, value:,fuzzy:, association_key_column:)
+          likeval = get_like_value(value,fuzzy)
+
+          association_op = nil
           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)
+            association_op = :not_null if association_key_column && !column_object
           when '!!'
             op = '='
             value = nil # Enforce it is indeed nil (should be)
+            association_op = :null if association_key_column && !column_object
+          end
+
+          if association_op
+            neg = association_op == :not_null ? true : false
+            qr = quote_right_part(query: query, value: nil, column_object: association_key_column, negative: neg)
+            return query.where("#{quote_column_path(query: query, prefix: column_prefix, column_object: association_key_column)} #{qr}")
+          end
+
+          # Add an AND along with the condition, which ensures the left outter join 'exists' for it
+          # Normally this wouldn't be necessary as a condition on a given value mathing would imply the related row was there
+          # but this is not the case for NULL conditions, as the foreign column would match a  NULL value, but not because the related column
+          # is NULL, but because the whole missing related row would appear with all fields null
+          # NOTE: we don't need to do it for conditions applying to the root of the tree (there isn't a join to it)
+          if association_key_column
+            qr = quote_right_part(query: query, value: nil, column_object: association_key_column, negative: true)
+            query = query.where("#{quote_column_path(query: query, prefix: column_prefix, column_object: association_key_column)} #{qr}")
           end
 
           case op
@@ -265,12 +313,22 @@ module Praxis
         end
 
         # Returns nil if the value was not a fuzzzy pattern
-        def self.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
 

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

@@ -15,7 +15,7 @@ module Praxis
             if components.empty?
               return
             elsif components.size == 1
-              @conditions << hash.slice(:name, :op, :value, :node_object)
+              @conditions << hash.slice(:name, :op, :value, :fuzzy, :node_object)
             else
               children_data[components.first] ||= []
               children_data[components.first] << hash

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

@@ -182,7 +182,7 @@ module Praxis
               else
                 spec[:values]
               end
-            accum.push(name: attr_name, op: spec[:op], value: coerced , node_object: spec[:node_object])
+            accum.push(name: attr_name, op: spec[:op], value: coerced , fuzzy: spec[:fuzzies], node_object: spec[:node_object])
           end
           new(accum)
         end
@@ -222,10 +222,9 @@ module Praxis
             value_type = attr_filters[:value_type]
             next unless value_type == Attributor::String
 
-            value = item[:value]
-            unless value.empty?
+            if item[:value].presence
               fuzzy_match = attr_filters[:fuzzy_match]
-              if (value[-1] == '*' || value[0] == '*') && !fuzzy_match
+              if item[:fuzzy] && !item[:fuzzy].empty? && !fuzzy_match
                 errors << "Fuzzy matching for #{attr_name} is not allowed (yet '*' was found in the value)"
               end
             end

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

@@ -15,41 +15,81 @@ module Praxis
           #   Example: [{:name=>"multi"@0, :op=>"="@5}, {:value=>"1"@6}, {:value=>"2"@8}]
           def initialize(triad:, parent_group:)
             @parent_group = parent_group
-
             if triad.is_a? Array # several values coming in
               spec, *values = triad
               @name = spec[:name].to_sym
               @op = spec[:op].to_s
 
-              @values = if values.empty?
-                ""
+              if values.empty?
+                @values = ""
+                @fuzzies = nil
               elsif values.size == 1
-                CGI.unescape(values.first[:value].to_s)
+                raw_val = values.first[:value].to_s
+                @values, @fuzzies = _compute_fuzzy(values.first[:value].to_s)
               else
-                values.map{|e| CGI.unescape(e[:value].to_s)}
+                @values = []
+                @fuzzies = []
+                results = values.each do|e| 
+                  val, fuz = _compute_fuzzy(e[:value].to_s)
+                  @values.push val
+                  @fuzzies.push fuz
+                end
               end
             else # No values for the operand
               @name = triad[:name].to_sym
               @op = triad[:op].to_s
               if ['!','!!'].include?(@op)
-                @values = nil
+                @values, @fuzzies = [nil, nil]
               else
                 # Value operand without value? => convert it to empty string
                 raise "Interesting, didn't know this could happen. Oops!" if triad[:value].is_a?(Array) && !triad[:value].empty?
-                @values = (triad[:value] == []) ? '' : CGI.unescape(triad[:value].to_s) # TODO: could this be an array (or it always comes the other if)
+                if triad[:value] == []
+                  @values, @fuzzies = ['', nil]
+                else
+                  @values, @fuzzies = _compute_fuzzy(triad[:value].to_s)
+                end
               end
             end
           end
-        
+          # Takes a raw val, and spits out the output val (unescaped), and the fuzzy definition
+          def _compute_fuzzy(raw_val)
+            starting = raw_val[0] == '*'
+            ending = raw_val[-1] == '*'
+            newval, fuzzy = if starting && ending
+              [raw_val[1..-2], :start_end]
+            elsif starting
+              [raw_val[1..-1], :start]
+            elsif ending
+              [raw_val[0..-2], :end]
+            else
+              [raw_val,nil]
+            end
+            newval = CGI.unescape(newval) if newval
+            [newval,fuzzy]
+          end
           def flattened_conditions
-            [{name: @name, op: @op, values: @values, node_object: self}]
+            [{name: @name, op: @op, values: @values, fuzzies: @fuzzies, node_object: self}]
           end
 
+          # Dumps the value, marking where the fuzzy might be, and removing the * to differentiate from literals
+          def _dump_value(val,fuzzy)
+            case fuzzy
+            when nil
+              val
+            when :start_end
+              '{*}' + val + '{*}'
+            when :start
+              '{*}' + val
+            when :end
+               val +'{*}'
+            end
+          end
           def dump
             vals = if values.is_a? Array
-              "[#{values.join(',')}]" # Purposedly enclose in brackets to make sure we differentiate
+              dumped = values.map.with_index{|val,i| _dump_value(val, @fuzzies[i])}
+              "[#{dumped.join(',')}]" # Purposedly enclose in brackets to make sure we differentiate
             else
-              (values == '') ? "\"#{values}\"" : values # Dump the empty string explicitly with quotes if we've converted no value to empty string
+              (values == '') ? '""' : _dump_value(values,@fuzzies) # Dump the empty string explicitly with quotes if we've converted no value to empty string
             end
             "#{name}#{op}#{vals}"
           end
@@ -134,7 +174,7 @@ module Praxis
           end
    
           rule(:name)    { match('[a-zA-Z0-9_\.]').repeat(1) } # TODO: are these the only characters that we allow for names?
-          rule(:chars) { match('[^&|),]').repeat(0).as(:value) }
+          rule(:chars) { match('[^&|(),]').repeat(0).as(:value) }
           rule(:value)    { chars >> (comma >> chars ).repeat }
 
           rule(:triad)  {