praxis 0.21 → 0.22.pre.1

data/lib/praxis/controller.rb

@@ -20,6 +20,8 @@ module Praxis
         end
 
         definition.controller = self
+        # `implements` should only be processed while the application initializes/setup
+        # So we will use the `.instance` function to get the "current" application instance
         Application.instance.controllers << self
       end
 

data/lib/praxis/dispatcher.rb

@@ -28,11 +28,13 @@ module Praxis
       @deferred_callbacks[:after] << [conditions, block]
     end
 
-    def self.current(thread: Thread.current, application: Application.instance)
+    # Typically, this is only called from the router, and the app will always be known.
+    # But we'll leave the application param as optional if we know there is a dispatcher in the thread
+    def self.current(thread: Thread.current, application: nil)
       thread[:praxis_dispatcher] ||= self.new(application: application)
     end
 
-    def initialize(application: Application.instance)
+    def initialize(application:)
       @stages = []
       @application = application
       setup_stages!
@@ -76,8 +78,17 @@ module Praxis
       @action = action
       @request = request
 
-      payload = {request: request, response: nil}
+      payload = {request: request, response: nil, controller: @controller}
 
+      instrumented_dispatch( payload )
+
+    ensure
+      @controller = nil
+      @action = nil
+      @request = nil
+    end
+
+    def instrumented_dispatch( payload )
       Notifications.instrument 'praxis.request.all'.freeze, payload do
         begin
           # the response stage must be the final stage in the list
@@ -95,18 +106,13 @@ module Praxis
           response_stage.run
 
           payload[:response] = controller.response
-          controller.response.finish
+          controller.response.finish(application: application)
         rescue => e
-          @application.error_handler.handle!(request, e)
+          @application.error_handler.handle!(request, e, app: application)
         end
       end
-    ensure
-      @controller = nil
-      @action = nil
-      @request = nil
     end
 
-
     # TODO: fix for multithreaded environments
     def reset_cache!
       return unless Praxis::Blueprint.caching_enabled?

data/lib/praxis/docs/generator.rb

@@ -5,7 +5,8 @@ module Praxis
       require 'active_support/core_ext/enumerable' # For index_by
 
       API_DOCS_DIRNAME = 'docs/api'
-
+      
+      attr_reader :app_instance
       attr_reader :resources_by_version, :types_by_id, :infos_by_version
       attr_reader :doc_root_dir
 
@@ -20,16 +21,25 @@ module Praxis
         Attributor::Integer,
         Attributor::Object,
         Attributor::String,
-        Attributor::Symbol
+        Attributor::Symbol,
+        Attributor::URI,
       ]).freeze
 
-
-      def initialize(root)
+      def self.generate(root, name:, skip_sub_directory: false)
+        instance = Praxis::Application.registered_apps[name]
+        Thread.current[:praxis_instance] = instance
+        self.new(root, instance: instance, name: name, skip_sub_directory: skip_sub_directory).save!
+        Thread.current[:praxis_instance] = nil
+      end
+      
+      def initialize(root, instance:, name:, skip_sub_directory:)
         require 'yaml'
         @resources_by_version =  Hash.new do |h,k|
           h[k] = Set.new
         end
-        initialize_directories(root)
+        @app_instance = instance
+        subdir = skip_sub_directory ? nil : name
+        initialize_directories(root, subdir: subdir )
 
         Attributor::AttributeResolver.current = Attributor::AttributeResolver.new
         collect_infos
@@ -47,9 +57,10 @@ module Praxis
 
       private
 
-      def initialize_directories(root)
+      def initialize_directories(root, subdir: nil )
         @doc_root_dir = File.join(root, API_DOCS_DIRNAME)
-
+        @doc_root_dir = File.join(@doc_root_dir, subdir) if subdir
+        
         # remove previous data (and reset the directory)
         FileUtils.rm_rf @doc_root_dir if File.exists?(@doc_root_dir)
         FileUtils.mkdir_p @doc_root_dir unless File.exists? @doc_root_dir
@@ -57,7 +68,7 @@ module Praxis
 
       def collect_resources
         # load all resource definitions registered with Praxis
-        Praxis::Application.instance.resource_definitions.map do |resource|
+        app_instance.resource_definitions.map do |resource|
           # skip resources with doc_visibility of :none
           next if resource.metadata[:doc_visibility] == :none
           version = resource.version
@@ -75,7 +86,7 @@ module Praxis
 
       def collect_infos
         # All infos. Including keys for `:global`, "n/a", and any string version
-        @infos_by_version = ApiDefinition.instance.describe
+        @infos_by_version = app_instance.api_definition.describe
       end
 
 

data/lib/praxis/docs/link_builder.rb

@@ -20,7 +20,7 @@ module Praxis
 
       def endpoint
         @endpoint ||= begin
-          endpoint = ApiDefinition.instance.global_info.documentation_url
+          endpoint = Application.current_instance.api_definition.global_info.documentation_url
           endpoint.gsub(/\/index\.html$/i, '/') if endpoint
         end
       end

data/lib/praxis/error_handler.rb

@@ -1,15 +1,15 @@
 module Praxis
   class ErrorHandler
-
-    def handle!(request, error)
-      Application.instance.logger.error error.inspect
+    
+    def handle!(request, error, app:)
+      app.logger.error error.inspect
       error.backtrace.each do |line|
-        Application.instance.logger.error line
+        app.logger.error line
       end
 
       response = Responses::InternalServerError.new(error: error)
       response.request = request
-      response.finish
+      response.finish(application: app)
     end
 
   end

data/lib/praxis/extensions/attribute_filtering.rb

@@ -0,0 +1,28 @@
+require 'praxis/extensions/attribute_filtering/filtering_params'
+require 'praxis/extensions/attribute_filtering/query_builder'
+
+# To include in a controller
+module Praxis
+  module Extensions
+    module AttributeFiltering
+      extend ActiveSupport::Concern
+      
+      def build_query(base_query) # rubocop:disable Metrics/AbcSize
+
+        domain_model = self.media_type&.domain_model
+        raise "No domain model defined for #{self.name}. Cannot use the attribute filtering helpers without it" unless domain_model
+        
+        filters = request.params.filters if request.params&.respond_to?(:filters)
+        base_query = domain_model.craft_query( base_query , filters )
+
+        # TODO: add the field selector...and the pagination...and the ordering...
+        resolved = Praxis::MediaType::FieldResolver.resolve(self.media_type, self.expanded_fields)
+        base_query = FieldSelection::ActiveRecordQuerySelector.new(ds: base_query, model: domain_model.model,
+                                        selectors: identity_map.selectors, resolved: resolved).generate
+
+        # TODO: handle pagination and ordering
+        base_query
+      end
+    end
+  end
+end

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

@@ -0,0 +1,180 @@
+module Praxis
+  module Extensions
+    class ActiveRecordFilterQueryBuilder
+    attr_reader :query, :table, :model
+
+    # Abstract class, which needs to be used by subclassing it through the .for method, to set the mapping of attributes
+    class << self
+      def for(definition)
+        Class.new(self) do
+          @attr_to_column = case definition
+                            when Hash
+                                definition
+                              when Array
+                                definition.each_with_object({}) { |item, hash| hash[item.to_sym] = item }
+                              else
+                                raise "Cannot use FilterQueryBuilder.of without passing an array or a hash (Got: #{definition.class.name})"
+                              end
+            class << self
+              attr_reader :attr_to_column
+            end
+          end
+        end
+      end
+
+      # Base query to build upon
+      def initialize(query: , model: )
+        @query = query
+        @table = model.table_name
+        @last_join_alias = model.table_name
+        @alias_counter = 0;
+      end
+
+      def pick_alias( name )
+        @alias_counter += 1
+        "#{name}#{@alias_counter}"
+      end
+
+      def build_clause(filters)
+        filters.each do |item|
+          attr = item[:name]
+          spec = item[:specs]
+          column_name = attr_to_column[attr]
+          raise "Filtering by #{attr} not allowed (no mapping found)" unless column_name
+          if column_name.is_a?(Proc)
+            bindings = column_name.call(spec)
+            # A hash of bindings, consisting of a key with column name and a value to the query value
+            bindings.each do|col,val|
+              assoc_or_field, *rest = col.to_s.split('.')
+              expand_binding(column_name: assoc_or_field, rest: rest, op: spec[:op], value: val, use_this_name_for_clause: @last_join_alias)
+            end
+          else
+            assoc_or_field, *rest = column_name.to_s.split('.')
+            expand_binding(column_name: assoc_or_field, rest: rest, **spec, use_this_name_for_clause: @last_join_alias)
+          end
+        end
+        query
+      end
+
+      # TODO: Support more relationship types (including things like polymorphic..etc)
+      def do_join(query, assoc , source_alias, table_alias)
+        reflection = query.reflections[assoc.to_s]
+         do_join_reflection( query, reflection, source_alias, table_alias )
+      end
+
+      def do_join_reflection( query, reflection, source_alias, table_alias )
+        c = query.connection
+        case reflection
+        when ActiveRecord::Reflection::BelongsToReflection
+          join_clause = "INNER JOIN %s as %s ON %s.%s = %s.%s " % \
+                [c.quote_table_name(reflection.klass.table_name),
+                  c.quote_table_name(table_alias),
+                  c.quote_table_name(table_alias),
+                  c.quote_column_name(reflection.association_primary_key),
+                  c.quote_table_name(source_alias),
+                  c.quote_column_name(reflection.association_foreign_key)
+                 ]
+          query.joins(join_clause)
+        when ActiveRecord::Reflection::HasManyReflection
+    #        join_clause = "INNER JOIN #{reflection.klass.table_name} as #{table_alias} ON"  + \
+    #              " \"#{source_alias}\".\"id\" = \"#{table_alias}\".\"#{reflection.foreign_key}\" "
+          join_clause = "INNER JOIN %s as %s ON %s.%s = %s.%s " % \
+                [c.quote_table_name(reflection.klass.table_name),
+                  c.quote_table_name(table_alias),
+                  c.quote_table_name(source_alias),
+                  c.quote_column_name(reflection.active_record.primary_key),
+                  c.quote_table_name(table_alias),
+                  c.quote_column_name(reflection.foreign_key)
+                 ]
+
+          if reflection.type # && reflection.options[:as]....
+    #          addition = " AND \"#{table_alias}\".\"#{reflection.type}\" = \'#{reflection.active_record.class_name}\'"
+            addition = " AND %s.%s = %s" % \
+            [ c.quote_table_name(table_alias),
+              c.quote_table_name(reflection.type),
+              c.quote(reflection.active_record.class_name)]
+
+            join_clause += addition
+          end
+          query.joins(join_clause)
+        when ActiveRecord::Reflection::ThroughReflection
+          #puts "TODO: choose different alias (based on matching table type...)"
+          talias = pick_alias(reflection.through_reflection.table_name)
+          salias = source_alias
+
+          query = do_join_reflection(query, reflection.through_reflection, salias, talias)
+          #puts "TODO: choose different alias ?????????"
+          salias = talias
+
+          through_model = reflection.through_reflection.klass
+          through_assoc = reflection.name
+          final_reflection = reflection.source_reflection
+
+          do_join_reflection(query, final_reflection, salias, table_alias)
+        else
+          raise "Joins for this association type are currently UNSUPPORTED: #{reflection.inspect}"
+        end
+      end
+
+      def expand_binding(column_name:,rest: , op:,value:, use_this_name_for_clause: column_name)
+        unless rest.empty?
+          joined_alias = pick_alias(column_name)
+          @query = do_join(query, column_name, @last_join_alias, joined_alias)
+          saved_join_alias = @last_join_alias
+          @last_join_alias = joined_alias
+          new_column_name, *new_rest = rest
+          expand_binding(column_name: new_column_name, rest: new_rest, op: op, value: value, use_this_name_for_clause: joined_alias)
+          @last_join_alias = saved_join_alias          
+        else
+          column_name = "#{use_this_name_for_clause}.#{column_name}"
+          add_clause(column_name: column_name, op: op, value: value)
+        end
+      end
+
+      def attr_to_column
+        # Class method defined by the subclassing Class (using .for)
+        self.class.attr_to_column
+      end
+
+      # Private to try to funnel all column names through `build_clause` that restricts
+      # the attribute names better (to allow more difficult SQL injections )
+      private def add_clause(column_name:, op:, value:)
+        likeval = get_like_value(value)
+        @query =  case op
+                  when '='
+                    if likeval
+                      query.where("#{column_name} LIKE ?", likeval)
+                    else
+                      query.where(column_name => value)
+                    end
+                  when '!='
+                    if likeval
+                      query.where("#{column_name} NOT LIKE ?", likeval)
+                    else
+                      query.where.not(column_name => value)
+                    end
+                  when '>'
+                    query.where("#{column_name} > ?", value)
+                  when '<'
+                    query.where("#{column_name} < ?", value)
+                  when '>='
+                    query.where("#{column_name} >= ?", value)
+                  when '<='
+                    query.where("#{column_name} <= ?", value)
+                  else
+                    raise "Unsupported Operator!!! #{op}"
+                  end
+      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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+# rubocop:disable all
+#
+# Attributor type to define and handlea simple language to express filtering attributes in listings.
+# Commonly used in a query string parameter value for listing calls.
+# 
+# The type allows you to restrict the allowable fields (and their types) based on an existing Mediatype.
+# It also alows you to define exacly what fields (from that MediaType) are allowed, an what operations are
+# supported for each of them. Includes most in/equalities and fuzzy matching options(i.e., leading/trailing `*` )
+#
+# Example syntax:  `status=open&time>2001-1-1&name=*Bar`
+#
+# Example use and definition of the type:
+# attribute :filters,
+#           Types::FilteringParams.for(MediaTypes::MyType) do
+#   filter 'user.id', using: ['=', '!=']
+#   filter 'name', using: ['=', '!=']
+#   filter 'children.created_at', using: ['>', '>=', '<', '<=']
+#   filter 'display_name', using: ['=', '!='], fuzzy: true
+# end
+
+module Praxis
+  module Extensions
+    module AttributeFiltering
+      class FilteringParams
+        include Attributor::Type
+        include Attributor::Dumpable
+  
+        # This DSL allows to define which attributes are allowed in the filters, and with which operators
+        class DSLCompiler < Attributor::DSLCompiler
+          # "account.id": { operators: ["=", "!="] },
+          # name:         { operators: ["=", "!="], fuzzy_match: true },
+          # start_date:   { operators: ["!=", ">=", "<=", "=", "<", ">"] }
+          #
+          def filter(name, using: nil, fuzzy: false)
+            target.add_filter(name.to_sym, operators: Set.new(using), fuzzy: fuzzy)
+          end
+        end
+  
+        VALUE_REGEX = /[^,&]*/
+        AVAILABLE_OPERATORS = Set.new(['!=', '>=', '<=', '=', '<', '>']).freeze
+        FILTER_REGEX = /(?<attribute>([^=!><])+)(?<operator>!=|>=|<=|=|<|>)(?<value>#{VALUE_REGEX}(,#{VALUE_REGEX})*)/
+  
+        # Abstract class, which needs to be used by subclassing it through the .for method, to set the allowed filters
+        # definition should be a hash, keyed by field name, which contains a hash that can have two pieces of metadata
+        # :operators => an array of operators allowed (if empty, means all)
+        # :value_type => a type class which the value should match
+        # :fuzzy_match => weather or not we allow a "like" type query (for prefix or suffix matching)
+        class << self
+          attr_reader :media_type
+          attr_reader :allowed_filters
+  
+          def for(media_type, **_opts)
+            unless media_type < Praxis::MediaType
+              raise ArgumentError, "Invalid type: #{media_type.name} for Filters. " \
+                'Must be a subclass of MediaType'
+            end
+  
+            ::Class.new(self) do
+              @media_type = media_type
+              @allowed_filters = {}
+            end
+          end
+  
+          def add_filter(name, operators:, fuzzy:)
+            components = name.to_s.split('.').map(&:to_sym)
+            attribute, enclosing_type = find_filter_attribute(components, media_type)
+            raise 'Invalid set of operators passed' unless AVAILABLE_OPERATORS.superset?(operators)
+  
+            @allowed_filters[name] = {
+              value_type: attribute.type,
+              operators: operators,
+              fuzzy_match: fuzzy
+            }
+          end
+        end
+  
+        attr_reader :parsed_array
+  
+        def self.native_type
+          self
+        end
+  
+        def self.name
+          'Praxis::Types::FilteringParams'
+        end
+  
+        def self.display_name
+          'Filtering'
+        end
+  
+        def self.family
+          'string'
+        end
+  
+        def self.constructable?
+          true
+        end
+  
+        def self.construct(definition, **options)
+          return self if definition.nil?
+  
+          DSLCompiler.new(self, options).parse(*definition)
+          self
+        end
+  
+        def self.find_filter_attribute(name_components, type)
+          type = type.member_type if type < Attributor::Collection
+          first, *rest = name_components
+          first_attr = type.attributes[first]
+          unless first_attr
+            raise "Error, you've requested to filter by field #{first} which does not exist in the #{type.name} mediatype!\n"
+          end
+  
+          return find_filter_attribute(rest, first_attr.type) if rest.present?
+  
+          [first_attr, type] # Return the attribute and associated enclosing type
+        end
+  
+        def self.example(_context = Attributor::DEFAULT_ROOT_CONTEXT, **_options)
+          fields = if media_type
+                     mt_example = media_type.example
+                     pickable_fields = mt_example.object.keys & allowed_filters.keys
+                     pickable_fields.sample(2).each_with_object([]) do |filter_name, arr|
+                       op = allowed_filters[filter_name][:operators].to_a.sample(1).first
+  
+                       # Switch this to pick the right example attribute from the mt example
+                       filter_components = filter_name.to_s.split('.').map(&:to_sym)
+                       mapped_attribute, _enclosing_type = find_filter_attribute(filter_components, media_type)
+                       unless mapped_attribute
+                         raise "filter with name #{filter_name} does not correspond to an existing field inside " \
+                               " MediaType #{media_type.name}"
+                       end
+                       attr_example = filter_components.inject(mt_example) do |last, name|
+                         # we can safely do sends, since we've verified the components are valid
+                         last.send(name)
+                       end
+                       arr << "#{filter_name}#{op}#{attr_example}"
+                     end.join('&')
+                   else
+                     'name=Joe&date>2017-01-01'
+                   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(filters, _context = Attributor::DEFAULT_ROOT_CONTEXT, **_options)
+          return filters if filters.is_a?(native_type)
+          return new if filters.nil?
+          parsed = filters.split('&').each_with_object([]) do |filter_string, arr|
+            match = FILTER_REGEX.match(filter_string)
+            values = CGI.unescape(match[:value]).split(',')
+            value = if values.size > 1
+              multimatch = true
+              values
+            else
+              multimatch = false
+              match[:value]
+            end
+  
+            attr_name = match[:attribute].to_sym
+            # TODO: we should coerce values if there's a mediatype defined?
+            coerced = if media_type
+              filter_components = attr_name.to_s.split('.').map(&:to_sym)
+              attr, _enclosing_type = find_filter_attribute(filter_components, media_type)
+              if multimatch
+                attr_coll = Attributor::Collection.of(attr.type)
+                attr_coll.load(value)
+              else
+                attr.load(value)
+              end
+            else
+              value
+            end
+            arr.push(name: attr_name, specs: { op: match[:operator], value: coerced } )
+          end
+          new(parsed)
+        end
+  
+        def self.dump(value, **_opts)
+          load(value).dump
+        end
+  
+        def self.describe(_root = false, example: nil)
+          hash = super
+          if allowed_filters
+            hash[:filters] = allowed_filters.each_with_object({}) do |(name, spec), accum|
+              accum[name] = { operators: spec[:operators].to_a }
+              accum[name][:fuzzy] = true if spec[:fuzzy_match]
+            end
+          end
+  
+          hash
+        end
+  
+        def initialize(parsed = [])
+          @parsed_array = parsed
+        end
+  
+        def validate(_context = Attributor::DEFAULT_ROOT_CONTEXT)
+          parsed_array.each_with_object([]) do |item, errors|
+            attr_name = item[:name]
+            specs = item[:specs]
+            attr_filters = allowed_filters[attr_name]
+            unless attr_filters
+              errors << "Filtering by #{attr_name} is not allowed. You can filter by #{allowed_filters.keys.map(&:to_s).join(', ')}"
+              next
+            end
+            allowed_operators = attr_filters[:operators]
+            unless allowed_operators.include?(specs[:op])
+              errors << "Operator #{specs[:op]} not allowed for filter #{attr_name}"
+            end
+            value_type = attr_filters[:value_type]
+            value = specs[:value]
+            if value_type && !value_type.valid_type?(value)
+              # Allow a collection of values of the right type for multimatch (if operators are = or !=)
+              if ['=','!='].include?(specs[:op])
+                coll_type = Attributor::Collection.of(value_type)
+                if !coll_type.valid_type?(value)
+                  errors << "Invalid type in filter/s value for #{attr_name} " +\
+                            "(one or more of the multiple matches in #{value} are not  a #{value_type.name.split('::').last})"
+                end
+              else
+                errors << "Invalid type in filter value for #{attr_name} (#{value} using '#{specs[:op]}' is not a #{value_type.name.split('::').last})"
+              end
+            end
+  
+            next unless value_type == Attributor::String
+            unless value.empty?
+              fuzzy_match = attr_filters[:fuzzy_match]
+              if (value[-1] == '*' || value[0] == '*') && !fuzzy_match
+                errors << "Fuzzy matching for #{attr_name} is not allowed (yet '*' was found in the value)"
+              end
+            end
+          end
+        end
+  
+        # Dump back string parseable form
+        def dump
+          parsed_array.each_with_object([]) do |item, arr|
+            field = item[:name]
+            spec = item[:specs]
+            arr << "#{field}#{spec[:op]}#{spec[:value]}"
+          end.join('&')
+        end
+  
+        def each
+          parsed_array&.each do |filter|
+            yield filter
+          end
+        end
+  
+        def allowed_filters
+          # Class method defined by the subclassing Class (using .for)
+          self.class.allowed_filters
+        end
+      end
+    end
+  end
+end
+
+# Alias it to a much shorter and sweeter name in the Types namespace.
+module Praxis
+  module Types
+    FilteringParams = Praxis::Extensions::AttributeFiltering::FilteringParams
+  end
+end
+
+# rubocop:enable all