praxis 2.0.pre.10 → 2.0.pre.15

data/lib/praxis/mapper/active_model_compat.rb

@@ -23,6 +23,10 @@ module Praxis
           Praxis::Extensions::FieldSelection::ActiveRecordQuerySelector
         end
 
+        def _pagination_query_builder_class
+          Praxis::Extensions::Pagination::ActiveRecordPaginationHandler
+        end
+
         def _praxis_associations
           orig = self.reflections.clone
 

data/lib/praxis/mapper/resource.rb

@@ -30,6 +30,7 @@ module Praxis::Mapper
         end
 
         @properties = self.superclass.properties.clone
+        @_filters_map = {}
       end
 
     end
@@ -197,7 +198,7 @@ module Praxis::Mapper
 
     # TODO: this shouldn't be needed if we incorporate it with the properties of the mapper...
     # ...maybe what this means is that we can change it for a better DSL in the resource?
-    def self.filters_mapping(definition)
+    def self.filters_mapping(definition={})
       @_filters_map = \
         case definition
         when Hash
@@ -211,7 +212,9 @@ module Praxis::Mapper
 
     def self.craft_filter_query(base_query, filters:) # rubocop:disable Metrics/AbcSize
       if filters 
-        raise "Must define the mapping of filters if want to use Filtering for resource: #{self}" unless @_filters_map
+        unless @_filters_map
+          raise "To use API filtering, you must define the mapping of api-names to resource properties (using the `filters_mapping` method in #{self})"
+        end
         debug = Praxis::Application.instance.config.mapper.debug_queries
         base_query = model._filter_query_builder_class.new(query: base_query, model: model, filters_map: @_filters_map, debug: debug).generate(filters)
       end
@@ -228,6 +231,19 @@ module Praxis::Mapper
       base_query
     end
 
+    def self.craft_pagination_query(base_query, pagination: ) # rubocop:disable Metrics/AbcSize
+      handler_klass = model._pagination_query_builder_class
+      return base_query unless (handler_klass && (pagination.paginator || pagination.order))
+
+      # Gather and save the count if required
+      if pagination.paginator&.total_count
+        pagination.total_count = handler_klass.count(base_query.dup)
+      end
+      
+      base_query = handler_klass.order(base_query, pagination.order)
+      handler_klass.paginate(base_query, pagination)
+    end
+
     def initialize(record)
       @record = record
     end

data/lib/praxis/mapper/selector_generator.rb

@@ -141,6 +141,7 @@ module Praxis::Mapper
     def add(resource, fields)
       @root = SelectorGeneratorNode.new(resource)
       @root.add(fields)
+      self
     end
 
     def selectors

data/lib/praxis/mapper/sequel_compat.rb

@@ -7,6 +7,9 @@ module Praxis::Mapper
 
     included do
       attr_accessor :_resource
+      class <<self  
+        alias_method :find_by, :find # Easy way to be method compatible with AR
+      end       
     end
 
     module ClassMethods
@@ -19,6 +22,10 @@ module Praxis::Mapper
         Praxis::Extensions::FieldSelection::SequelQuerySelector
       end
 
+      def _pagination_query_builder_class
+        Praxis::Extensions::Pagination::SequelPaginationHandler
+      end
+
       def _praxis_associations
         orig = self.association_reflections.clone
         orig.each do |k,v|

data/lib/praxis/media_type_identifier.rb

@@ -198,10 +198,20 @@ module Praxis
       obj = self.class.new
       obj.type = self.type
       obj.subtype = self.subtype
-      obj.suffix = suffix || self.suffix || ''
+      target_suffix = suffix || self.suffix
+      obj.suffix = redundant_suffix(target_suffix) ? '' : target_suffix
       obj.parameters = self.parameters.merge(parameters)
 
       obj
     end
+
+    def redundant_suffix(suffix)
+      # application/json does not need to be suffixed with +json (same for application/xml)
+      # we're supporting text/json and text/xml for older formats as well
+      if (self.type == 'application' || self.type == 'text') && self.subtype == suffix
+        return true
+      end
+      false
+    end
   end
 end

data/lib/praxis/plugins/mapper_plugin.rb

@@ -1,10 +1,23 @@
 require 'singleton'
 
+require 'praxis/extensions/field_selection'
+
 module Praxis  
   module Plugins
     module MapperPlugin
       include Praxis::PluginConcern
 
+      # The Mapper plugin is an overarching set of things to include in your application
+      # when you want to use the rendring, field_selection, filtering (and potentially pagination) extensions
+      # To use the plugin, set it up like any other plugin by registering to the bootloader.
+      # Typically you'd do that in environment.rb, inside the `Praxis::Application.configure do |application|` block, by:
+      #   application.bootloader.use Praxis::Plugins::MapperPlugin
+      #
+      # The plugin accepts only 1 configuration option thus far, which you can set inside the same block as:
+      #   application.config.mapper.debug_queries = true
+      # when debug_queries is set to true, the system will output information about the expanded fields 
+      # and associations that the system ihas calculated necessary to pull from the DB, based on the requested
+      # API fields, API filters and `property` dependencies defined in the domain models (i.e., resources)
       class Plugin < Praxis::Plugin
         include Singleton
 
@@ -28,17 +41,11 @@ module Praxis
         extend ActiveSupport::Concern
 
         included do
+          include Praxis::Extensions::Rendering
           include Praxis::Extensions::FieldExpansion
         end
 
-        def set_selectors
-          return unless self.media_type.respond_to?(:domain_model) &&
-            self.media_type.domain_model < Praxis::Mapper::Resource
-
-          selector_generator.add(self.media_type.domain_model, self.expanded_fields)
-        end
-
-        def build_query(base_query, type: :active_record) # rubocop:disable Metrics/AbcSize
+        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
           
@@ -47,18 +54,20 @@ module Praxis
           base_query = domain_model.craft_filter_query( base_query , filters: filters )
           # Handle field and nested field selection
           base_query = domain_model.craft_field_selection_query(base_query, selectors: selector_generator.selectors)
-          # handle pagination and ordering
-          base_query = _craft_pagination_query(query: base_query, type: type) if self.respond_to?(:_pagination)
+          # handle pagination and ordering if the pagination extention is included
+          base_query = domain_model.craft_pagination_query(base_query, pagination: _pagination)  if self.respond_to?(:_pagination)
 
           base_query
         end
 
         def selector_generator
-          @selector_generator ||= Praxis::Mapper::SelectorGenerator.new
-        end
+          return unless self.media_type.respond_to?(:domain_model) &&
+            self.media_type.domain_model < Praxis::Mapper::Resource
 
+          @selector_generator ||= \
+            Praxis::Mapper::SelectorGenerator.new.add(self.media_type.domain_model, self.expanded_fields)
+        end
       end
-
     end
   end
 end

data/lib/praxis/plugins/pagination_plugin.rb

@@ -1,14 +1,45 @@
 require 'singleton'
 require 'praxis/extensions/pagination'
 
-# Simple plugin concept
+# The PaginationPlugin can be configured to take advantage of adding pagination and sorting to
+# your DB queries.
+# When combined with the MapperPlugin, there is no extra configuration that needs to be done for
+# the system to appropriately identify the pagination and order parameters in the API, and translate
+# that in to the appropriate queries to fetch.
+# 
+# To use this plugin without the MapperPlugin (probably a rare case), one can apply the appropriate
+# clauses onto a query, by directly calling (in the controller) the `craft_pagination_query` method
+# of the domain_model associated to the controller's mediatype.
+# For example, here's how you can manually use this extension in a fictitious users index action:
+# def index
+#   base_query = User.all # Start by not excluding any user
+#   domain_model = self.media_type.domain_model
+#   objs = domain_model.craft_pagination_query(base_query, pagination: _pagination)
+#   display(objs)
+# end
+# 
+# This plugin accepts configuration about the default behavior of pagination.
+# Any of these configs can individually be overidden when defining each Pagination/Order parameters
+# in any of the Endpoint actions.
+#
 # Example configuration for this plugin
 # Praxis::Application.configure do |application|
 #   application.bootloader.use Praxis::Plugins::PaginationPlugin, {
+#     # The maximum number of results that a paginated response will ever allow
 #     max_items: 500,  # Unlimited by default,
+#     # The default page size to use when no `items` is specified
 #     default_page_size: 100,
-#     disallow_paging_by_default: false,
-#     # See all available options below
+#     # Disallows the use of the page type pagination mode when true (i.e., using 'page=' parameter)
+#     disallow_paging_by_default: true, # Default false
+#     # Disallows the use of the cursor type pagination mode when true (i.e., using 'by=' or 'from=' parameter)
+#     disallow_cursor_by_default: true, # Default false
+#     # The default mode params to use 
+#     paging_default_mode: {by: :uuid}, # Default {by: :uid}
+#     # Weather or not to enforce that all requested sort fields are part of the media_type attributes
+#     # when false (not enforced) only the first field would be checked
+#     sorting: {
+#       enforce_all_fields: false       # Default true 
+#     }
 #   end
 # end
 #
@@ -39,7 +70,6 @@ module Praxis
             attribute :paging_default_mode, Hash, default: Praxis::Types::PaginationParams.paging_default_mode
             attribute :disallow_paging_by_default, Attributor::Boolean, default: Praxis::Types::PaginationParams.disallow_paging_by_default
             attribute :disallow_cursor_by_default, Attributor::Boolean, default: Praxis::Types::PaginationParams.disallow_cursor_by_default
-            attribute :disallow_cursor_by_default, Attributor::Boolean, default: Praxis::Types::PaginationParams.disallow_cursor_by_default
             attribute :sorting do
               attribute :enforce_all_fields, Attributor::Boolean, default: Praxis::Types::OrderingParams.enforce_all_fields
             end

data/lib/praxis/response_definition.rb

@@ -55,52 +55,36 @@ module Praxis
       end
     end
 
-    def location(loc=nil)
-      return @spec[:location] if loc.nil?
-      unless ( loc.is_a?(Regexp) || loc.is_a?(String) )
-        raise Exceptions::InvalidConfiguration.new(
-          "Invalid location specification. Location in response must be either a regular expression or a string."
-        )
-      end
-      @spec[:location] = loc
-    end
+    def location(loc=nil, description: nil)
+      return  headers.dig('Location',:value) if loc.nil?
 
-    def headers(hdrs = nil)
-      return @spec[:headers] if hdrs.nil?
+      header('Location', loc, description: description)
+    end
 
-      case hdrs
-      when Array
-        hdrs.each {|header_name| header(header_name) }
-      when Hash
-        header(hdrs)
-      when String
-        header(hdrs)
-      else
-        raise Exceptions::InvalidConfiguration.new(
-          "Invalid headers specification: Arrays, Hash, or String must be used. Received: #{hdrs.inspect}"
-        )
-      end
+    def headers
+      @spec[:headers]
     end
 
-    def header(hdr)
-      case hdr
-      when String
-        @spec[:headers][hdr] = true
-      when Hash
-        hdr.each do | k, v |
-          unless v.is_a?(Regexp) || v.is_a?(String)
-            raise Exceptions::InvalidConfiguration.new(
-              "Header definitions for #{k.inspect} can only match values of type String or Regexp. Received: #{v.inspect}"
-            )
-          end
-          @spec[:headers][k] = v
-        end
+    def header(name, value, description: nil)
+      the_type, args = case value
+      when nil,String
+        [String, {}]
+      when Regexp
+        # A regexp means it's gonna be a String typed, attached to a regexp
+        [String, { regexp: value }]
       else
         raise Exceptions::InvalidConfiguration.new(
-          "A header definition can only take a String (to match the name) or" +
-          " a Hash (to match both the name and the value). Received: #{hdr.inspect}"
+          "A header definition for a response can only take String, Regexp or nil values (to match anything)." +
+          "Received the following value for header name #{name}: #{value}"
         )
       end
+
+      info = { 
+        value: value, 
+        attribute: Attributor::Attribute.new(the_type, **args)
+      }
+      info[:description] = description if description
+      @spec[:headers][name] = info
     end
 
     def example(context=nil)
@@ -123,13 +107,14 @@ module Praxis
         :status => status,
         :headers => {}
       }
-      content[:location] = _describe_header(location) unless location == nil
 
       unless headers == nil
         headers.each do |name, value|
           content[:headers][name] = _describe_header(value)
         end
       end
+      content[:location] = content[:headers]['Location']
+
 
       if self.media_type
         payload = media_type.describe(true)
@@ -173,14 +158,14 @@ module Praxis
     end
 
     def _describe_header(data)
-      data_type = data.is_a?(Regexp) ? :regexp : :string
-      data_value = data.is_a?(Regexp) ? data.inspect : data
+
+      data_type = data[:value].is_a?(Regexp) ? :regexp : :string
+      data_value = data[:value].is_a?(Regexp) ? data[:value].inspect : data[:value]
       { :value => data_value, :type => data_type }
     end
 
     def validate(response, validate_body: false)
       validate_status!(response)
-      validate_location!(response)
       validate_headers!(response)
       validate_content_type!(response)
       validate_parts!(response)
@@ -222,23 +207,13 @@ module Praxis
       end
     end
 
-
-    # Validates 'Location' header
-    #
-    # @raise [Exceptions::Validation] When location header does not match to the defined one.
-    #
-    def validate_location!(response)
-      return if location.nil? || location === response.headers['Location']
-      raise Exceptions::Validation.new("LOCATION does not match #{location.inspect}")
-    end
-
-
     # Validates Headers
     #
     # @raise [Exceptions::Validation]  When there is a missing required header..
     #
     def validate_headers!(response)
       return unless headers
+
       headers.each do |name, value|
         if name.is_a? Symbol
           raise Exceptions::Validation.new(
@@ -252,20 +227,25 @@ module Praxis
           )
         end
 
-        case value
-        when String
-          if response.headers[name] != value
-            raise Exceptions::Validation.new(
-              "Header #{name.inspect}, with value #{value.inspect} does not match #{response.headers[name]}."
-            )
-          end
-        when Regexp
-          if response.headers[name] !~ value
-            raise Exceptions::Validation.new(
-              "Header #{name.inspect}, with value #{value.inspect} does not match #{response.headers[name].inspect}."
-            )
-          end
+        errors = value[:attribute].validate(response.headers[name])
+
+        unless errors.empty? 
+          raise Exceptions::Validation.new("Header #{name.inspect}, with value #{value.inspect} does not match #{response.headers[name]}.")
         end
+        # case value
+        # when String
+        #   if response.headers[name] != value
+        #     raise Exceptions::Validation.new(
+        #       "Header #{name.inspect}, with value #{value.inspect} does not match #{response.headers[name]}."
+        #     )
+        #   end
+        # when Regexp
+        #   if response.headers[name] !~ value
+        #     raise Exceptions::Validation.new(
+        #       "Header #{name.inspect}, with value #{value.inspect} does not match #{response.headers[name].inspect}."
+        #     )
+        #   end
+        # end
       end
     end
 

data/lib/praxis/responses/http.rb

@@ -160,7 +160,9 @@ module Praxis
 
           media_type media_type if media_type
           location location if location
-          headers headers if headers
+          headers&.each do |(name, value)|
+            header(name: name, value: value)
+          end
         end
       end
 

data/lib/praxis/tasks/api_docs.rb

@@ -21,7 +21,10 @@ namespace :praxis do
         trap('INT') { s.shutdown }
         s.start
       end
-      `open http://localhost:#{docs_port}/`
+      # If there is only 1 version we'll feature it and open the browser onto it
+      versions = Dir.children(root)
+      featured_version = (versions.size < 2) ? "#{versions.first}/" : ''
+      `open http://localhost:#{docs_port}/#{featured_version}`
       wb.join
     end
     desc "Generate and package all OpenApi Docs into a zip, ready for a Web server (like S3...) to present it"

data/lib/praxis/tasks/routes.rb

@@ -7,14 +7,14 @@ namespace :praxis do
     table = Terminal::Table.new title: "Routes",
     headings:  [
       "Version", "Path", "Verb",
-      "Resource", "Action", "Implementation", "Options"
+      "Endpoint", "Action", "Implementation", "Options"
     ]
 
     rows = []
-    Praxis::Application.instance.endpoint_definitions.each do |resource_definition|
-      resource_definition.actions.each do |name, action|
+    Praxis::Application.instance.endpoint_definitions.each do |endpoint_definition|
+      endpoint_definition.actions.each do |name, action|
         method = begin
-          m = resource_definition.controller.instance_method(name)
+          m = endpoint_definition.controller.instance_method(name)
         rescue
           nil
         end
@@ -22,13 +22,13 @@ namespace :praxis do
         method_name = method ? "#{method.owner.name}##{method.name}" : 'n/a'
 
         row = {
-          resource: resource_definition.name,
+          resource: endpoint_definition.name,
           action: name,
           implementation: method_name,
         }
 
         unless action.route
-          warn "Warning: No routes defined for #{resource_definition.name}##{name}."
+          warn "Warning: No routes defined for #{endpoint_definition.name}##{name}."
           rows << row
         else
           route = action.route