praxis 0.22.pre.2 → 2.0.pre.1

data/lib/praxis/mapper/selector_generator.rb

@@ -0,0 +1,126 @@
+module Praxis::Mapper
+  # Generates a set of selectors given a resource and
+  # list of resource attributes.
+  class SelectorGenerator
+    attr_reader :selectors
+
+    def initialize
+      @selectors = Hash.new do |hash, key|
+        hash[key] = {select: Set.new, track: Set.new}
+      end
+      @seen = Hash.new do |hash, resource|
+        hash[resource] = Set.new
+      end
+    end
+
+    def add(resource, fields)
+      return if @seen[resource].include? fields
+      @seen[resource] << fields
+
+      fields.each do |name, field|
+        map_property(resource, name, field)
+      end
+    end
+
+    def select_all(resource)
+      selectors[resource.model][:select] = true
+    end
+
+    def map_property(resource, name, fields)
+      if resource.properties.key?(name)
+        add_property(resource, name, fields)
+      elsif resource.model._praxis_associations.key?(name)
+        add_association(resource, name, fields)
+      else
+        add_select(resource, name)
+      end
+    end
+
+    def add_select(resource, name)
+      return select_all(resource) if name == :*
+      return if selectors[resource.model][:select] == true
+
+      selectors[resource.model][:select] << name
+    end
+
+    def add_track(resource, name)
+      selectors[resource.model][:track] << name
+    end
+
+    def add_association(resource, name, fields)
+      association = resource.model._praxis_associations.fetch(name) do
+        raise "missing association for #{resource} with name #{name}"
+      end
+      associated_resource = resource.model_map[association[:model]]
+
+      case association[:type]
+      when :many_to_one
+        add_track(resource, name)
+        Array(association[:key]).each do |akey|
+          add_select(resource, akey)
+        end
+      when :one_to_many
+        add_track(resource, name)
+        Array(association[:key]).each do |akey|
+          add_select(associated_resource, akey)
+        end
+      when :many_to_many
+        # If we haven't explicitly added the "through" option in the association
+        # then we'll assume the underlying ORM is able to fill in the gap. We will
+        # simply add the fields for the associated resource below
+        if association.key? :through
+          head, *tail = association[:through]
+          new_fields = tail.reverse.inject(fields) do |thing, step|
+            {step => thing}
+          end
+          return add_association(resource, head, new_fields)
+        else
+          add_track(resource, name)
+        end
+      else
+        raise "no select applicable for #{association[:type].inspect}"
+      end
+
+      unless fields == true
+        # recurse into the field
+        add(associated_resource,fields)
+      end
+    end
+
+    def add_property(resource, name, fields)
+      dependencies = resource.properties[name][:dependencies]
+      if dependencies
+        dependencies.each do |dependency|
+          # if dependency includes the name, then map it directly as the field
+          if dependency == name
+            add_select(resource, name)
+          else
+            apply_dependency(resource, dependency)
+          end
+        end
+      end
+
+      head, *tail = resource.properties[name][:through]
+      return if head.nil?
+
+      new_fields = tail.reverse.inject(fields) do |thing, step|
+        {step => thing}
+      end
+
+      add_association(resource, head, new_fields)
+    end
+
+    def apply_dependency(resource, dependency)
+      case dependency
+      when Symbol
+        map_property(resource, dependency, {})
+      when String
+        head, tail = dependency.split('.').collect(&:to_sym)
+        raise "String dependencies can not be singular" if tail.nil?
+
+        add_association(resource, head, {tail => true})
+      end
+    end
+
+  end
+end

data/lib/praxis/mapper/sequel_compat.rb

@@ -0,0 +1,37 @@
+require 'active_support/concern'
+
+module Praxis::Mapper
+  module SequelCompat
+    extend ActiveSupport::Concern
+
+``    included do
+      attr_accessor :_resource
+    end
+
+    module ClassMethods
+      def _filter_query_builder_class
+        Praxis::Extensions::SequelFilterQueryBuilder
+      end
+
+      def _praxis_associations
+        orig = self.association_reflections.clone
+
+        orig.each do |k,v|
+          v[:model] = v.associated_class
+          if v.respond_to?(:primary_key)
+            v[:primary_key] = v.primary_key
+          else
+            # FIXME: figure out exactly what to do here. 
+            # not super critical, as we can't track these associations
+            # directly, but it would be nice to traverse these
+            # properly.
+            v[:primary_key] = :unsupported
+          end
+        end
+        orig
+      end
+
+    end
+
+  end
+end

data/lib/praxis/middleware_app.rb

@@ -2,39 +2,37 @@ module Praxis
   class MiddlewareApp
 
     attr_reader :target
+
     # Initialize the application instance with the desired args, and return the wrapping class.
     def self.for( **args )
       Class.new(self) do
-        class << self
-          attr_accessor :app_instance
-          attr_reader :app_name, :skip_registration
-        end
-        @app_name = args.delete(:name)
-        @skip_registration = args.delete(:skip_registration) || false
         @args = args
-        @app_instance = nil
-        
+        @setup_done = false
         def self.name
           'MiddlewareApp'
         end
         def self.args
           @args
         end
+        def self.setup_done
+          @setup_done
+        end
         def self.setup
-          app_instance.setup(**args)
+          @setup_done = true
+          Praxis::Application.instance.setup(**@args)
         end
       end
-    end
+     end
 
     def initialize( inner )
       @target = inner
-      self.class.app_instance = Praxis::Application.new(name: self.class.app_name, skip_registration: self.class.skip_registration)      
+      @setup_done = false
     end
-    
+
     def call(env)
-      # NOTE: Need to make sure somebody has properly called the setup above before this is called
-      #@app_instance ||= Praxis::Application.new.setup(**self.class.args) #I Think that's not right at all...
-      result = self.class.app_instance.call(env)
+      self.class.setup unless self.class.setup_done
+      
+      result = Praxis::Application.instance.call(env)
 
       unless ( [404,405].include?(result[0].to_i) && result[1]['X-Cascade'] == 'pass' )
         # Respect X-Cascade header if it doesn't specify 'pass'

data/lib/praxis/multipart/part.rb

@@ -10,7 +10,6 @@ module Praxis
     attr_accessor :headers_attribute
     attr_accessor :filename_attribute
     attr_accessor :default_handler
-    attr_accessor :application
 
     def self.check_option!(name, definition)
       case name
@@ -78,8 +77,7 @@ module Praxis
       @name = name
       @body = body
       @headers = headers
-      @application = Praxis::Application.current_instance
-      @default_handler = application.handlers['json']
+      @default_handler = Praxis::Application.instance.handlers['json']
 
       if content_type.nil?
         self.content_type = 'text/plain'
@@ -214,7 +212,7 @@ module Praxis
     end
 
     def handler
-      handlers = application.handlers
+      handlers = Praxis::Application.instance.handlers
       (content_type && handlers[content_type.handler_name]) || @default_handler
     end
 
@@ -251,7 +249,7 @@ module Praxis
 
       # and return that one if it already corresponds to a registered handler
       # otherwise, add the encoding
-      if application.handlers.include?(pick.handler_name)
+      if Praxis::Application.instance.handlers.include?(pick.handler_name)
         return pick
       else
         return pick + handler_name

data/lib/praxis/plugins/mapper_plugin.rb

@@ -0,0 +1,50 @@
+require 'singleton'
+require 'praxis/extensions/attribute_filtering/filtering_params'
+
+module Praxis
+  module Plugins
+    module MapperPlugin
+      include Praxis::PluginConcern
+
+      class Plugin < Praxis::Plugin
+        include Singleton
+      end
+
+      module Controller
+        extend ActiveSupport::Concern
+
+        included do
+          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
+
+          resolved = Praxis::MediaType::FieldResolver.resolve(self.media_type, self.expanded_fields)
+          selector_generator.add(self.media_type.domain_model, resolved)
+        end
+
+        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_filter_query( base_query , filters: filters )
+
+          resolved = Praxis::MediaType::FieldResolver.resolve(self.media_type, self.expanded_fields)
+          base_query = domain_model.craft_field_selection_query(base_query, selectors: selector_generator.selectors, resolved: resolved)
+
+          # TODO: handle pagination and ordering
+          base_query
+        end
+
+        def selector_generator
+          @selector_generator ||= Praxis::Mapper::SelectorGenerator.new
+        end
+
+      end
+
+    end
+  end
+end

data/lib/praxis/request.rb

@@ -1,7 +1,7 @@
 module Praxis
 
   class Request < Praxis.request_superclass
-    attr_reader :env, :query, :praxis_instance
+    attr_reader :env, :query
     attr_accessor :route_params, :action
 
     PATH_VERSION_PREFIX = "/v".freeze
@@ -14,11 +14,10 @@ module Praxis
     API_NO_VERSION_NAME = 'n/a'.freeze
     VERSION_USING_DEFAULTS = [:header, :params].freeze
 
-    def initialize(env, args={})
+    def initialize(env)
       @env = env
       @query = Rack::Utils.parse_nested_query(env[QUERY_STRING_NAME])
       @route_params = {}
-      @praxis_instance = args[:application]
     end
 
     # Determine the content type of this request as indicated by the Content-Type header.
@@ -87,8 +86,8 @@ module Praxis
     PATH_VERSION_MATCHER = %r{^#{self.path_version_prefix}(?<version>[^\/]+)\/}.freeze
 
     def path_version_matcher
-      if praxis_instance.versioning_scheme == :path
-        matcher = Mustermann.new(praxis_instance.api_definition.info.base_path + '*')
+      if Application.instance.versioning_scheme == :path
+        matcher = Mustermann.new(ApiDefinition.instance.info.base_path + '*')
         matcher.params(self.path)[API_VERSION_PARAM_NAME]
       else
         PATH_VERSION_MATCHER.match(self.path)[:version]
@@ -97,7 +96,8 @@ module Praxis
 
     def version
       result = nil
-      Array(praxis_instance.versioning_scheme).find do |mode|
+
+      Array(Application.instance.versioning_scheme).find do |mode|
         case mode
         when :header;
           result = env[API_VERSION_HEADER_NAME]
@@ -128,7 +128,8 @@ module Praxis
     def load_payload(context)
       return unless action.payload
       return if content_type.nil?
-      raw = if (handler = praxis_instance.handlers[content_type.handler_name])
+
+      raw = if (handler = Praxis::Application.instance.handlers[content_type.handler_name])
         handler.parse(self.raw_payload)
       else
         # TODO is this a good default?
@@ -161,6 +162,12 @@ module Praxis
       @unmatched_versions ||= Set.new
     end
 
+    # Override the inspect instance method of a request, as, by default, the kernel inspect will go nuts
+    # traversing the action and app_instance and therefore all associated instance variables reachable through that
+    def inspect
+      "'@env' => #{@env.inspect},\n'@headers' => #{@headers.inspect},\n'@params' => #{@params.inspect},\n'@query' => #{@query.inspect}"
+    end
+
   end
 
 end

data/lib/praxis/request_stages/response.rb

@@ -8,9 +8,8 @@ module Praxis
 
         response.handle
 
-        config = Application.current_instance.config
-        if config.praxis.validate_responses == true
-          validate_body = config.praxis.validate_response_bodies
+        if Application.instance.config.praxis.validate_responses == true
+          validate_body = Application.instance.config.praxis.validate_response_bodies
 
           response.validate(action, validate_body: validate_body)
         end

data/lib/praxis/resource_definition.rb

@@ -8,15 +8,11 @@ module Praxis
     DEFAULT_RESOURCE_HREF_ACTION = :show
 
     included do
-      # Store the attached (i.e., current) Praxis App instance into the resource definition for easy retrieval later
-      @application = Application.instance
-      @application.resource_definitions << self
-
       @version = 'n/a'.freeze
       @actions = Hash.new
       @responses = Hash.new
 
-      @action_defaults = Trait.new &ResourceDefinition.generate_defaults_block(application: @application)
+      @action_defaults = Trait.new &ResourceDefinition.generate_defaults_block
 
       @version_options = {}
       @metadata = {}
@@ -37,12 +33,13 @@ module Praxis
 
       @on_finalize = Array.new
 
- 
+      Application.instance.resource_definitions << self
     end
 
-    def self.generate_defaults_block( version: nil, application:)
+    def self.generate_defaults_block( version: nil )
+
       # Ensure we inherit any base params defined in the API definition for the passed in version
-      base_attributes = if (base_params = application.api_definition.info(version).base_params)
+      base_attributes = if (base_params = ApiDefinition.instance.info(version).base_params)
         base_params.attributes
       else
         {}
@@ -59,8 +56,8 @@ module Praxis
       end
     end
 
-    def self.finalize!(application: )
-      application.resource_definitions.each do |resource_definition|
+    def self.finalize!
+      Application.instance.resource_definitions.each do |resource_definition|
         while (block = resource_definition.on_finalize.shift)
           block.call
         end
@@ -76,7 +73,6 @@ module Praxis
       attr_reader :traits
       attr_reader :version_prefix
       attr_reader :parent_prefix
-      attr_reader :application
 
       # opaque hash of user-defined medata, used to decorate the definition,
       # and also available in the generated JSON documents
@@ -203,7 +199,7 @@ module Praxis
           end
         end
 
-        @action_defaults.instance_eval &ResourceDefinition.generate_defaults_block( version: version, application: self.application)
+        @action_defaults.instance_eval &ResourceDefinition.generate_defaults_block( version: version )
       end
 
 
@@ -242,10 +238,10 @@ module Praxis
       end
 
       def trait(trait_name)
-        unless self.application.api_definition.traits.has_key? trait_name
+        unless ApiDefinition.instance.traits.has_key? trait_name
           raise Exceptions::InvalidTrait.new("Trait #{trait_name} not found in the system")
         end
-        trait = self.application.api_definition.traits.fetch(trait_name)
+        trait = ApiDefinition.instance.traits.fetch(trait_name)
         @traits << trait_name
       end
       alias_method :use, :trait

data/lib/praxis/response.rb

@@ -63,23 +63,24 @@ module Praxis
       self.class.response_name
     end
 
-    def format!(config:)
+    def format!
     end
 
-    def encode!(handlers:)
+    def encode!
       case @body
       when Hash, Array
         # response payload is structured data; transform it into an entity using the handler
         # implied by the response's media type. If no handler is registered for this
         # name, assume JSON as a default handler.
+        handlers = Praxis::Application.instance.handlers
         handler = (content_type && handlers[content_type.handler_name]) || handlers['json']
         @body = handler.generate(@body)
       end
     end
 
-    def finish(application:)
-      format!(config: application.config)
-      encode!(handlers: application.handlers)
+    def finish
+      format!
+      encode!
 
       @body = Array(@body)
 

data/lib/praxis/response_definition.rb

@@ -4,9 +4,8 @@ module Praxis
 
   class ResponseDefinition
     attr_reader :name
-    attr_reader :application
-    
-    def initialize(response_name, application, **spec, &block)
+
+    def initialize(response_name, **spec, &block)
       unless response_name
         raise Exceptions::InvalidConfiguration.new(
           "Response name is required for a response specification"
@@ -14,7 +13,6 @@ module Praxis
       end
       @spec = { headers:{} }
       @name = response_name
-      @application = application
       self.instance_exec(**spec, &block) if block_given?
 
       if self.status.nil?
@@ -143,9 +141,9 @@ module Praxis
           # FIXME: remove load when when MediaTypeCommon.identifier returns a MediaTypeIdentifier
           identifier = MediaTypeIdentifier.load(self.media_type.identifier)
 
-          default_handlers = application.api_definition.info.produces
+          default_handlers = ApiDefinition.instance.info.produces
 
-          handlers = application.handlers.select do |k,v|
+          handlers = Praxis::Application.instance.handlers.select do |k,v|
             default_handlers.include?(k)
           end
 
@@ -202,7 +200,7 @@ module Praxis
         raise ArgumentError, "Parts definition for response #{name} does not allow :like and a block simultaneously"
       end
       if like
-        template = application.api_definition.response(like)
+        template = ApiDefinition.instance.response(like)
         @parts = template.compile(nil, **args)
       else # block
         @parts = Praxis::ResponseDefinition.new('anonymous', **args, &a_proc)

data/lib/praxis/response_template.rb

@@ -1,12 +1,11 @@
 module Praxis
 
   class ResponseTemplate
-    attr_reader :name, :block, :application
+    attr_reader :name, :block
 
-    def initialize(response_name, application, &block)
+    def initialize(response_name, &block)
       @name = response_name
       @block = block
-      @application = application
     end
 
     def compile(action=nil, **args)
@@ -24,7 +23,7 @@ module Praxis
           args[:media_type] = media_type
         end
       end
-      Praxis::ResponseDefinition.new(name, application, **args, &block)   
+      Praxis::ResponseDefinition.new(name, **args, &block)   
     end
 
     def describe

data/lib/praxis/responses/http.rb

@@ -131,5 +131,41 @@ module Praxis
       self.status = 422
     end
 
+    ApiDefinition.define do |api|
+
+
+      [
+        [ :accepted, 202, "The request has been accepted for processing, but the processing has not been completed." ],
+        [ :no_content, 204,"The server successfully processed the request, but is not returning any content."],
+        [ :multiple_choices, 300,"Indicates multiple options for the resource that the client may follow."],
+        [ :moved_permanently, 301,"This and all future requests should be directed to the given URI."],
+        [ :found, 302,"The requested resource resides temporarily under a different URI."],
+        [ :see_other, 303,"The response to the request can be found under another URI using a GET method"],
+        [ :not_modified, 304,"Indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-Match."],
+        [ :temporary_redirect, 307,"In this case, the request should be repeated with another URI; however, future requests should still use the original URI."],
+        [ :bad_request, 400,"The request cannot be fulfilled due to bad syntax."],
+        [ :unauthorized, 401,"Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided."],
+        [ :forbidden, 403,"The request was a valid request, but the server is refusing to respond to it."],
+        [ :not_found, 404,"The requested resource could not be found but may be available again in the future."],
+        [ :method_not_allowed, 405,"A request was made of a resource using a request method not supported by that resource."],
+        [ :not_acceptable, 406,"The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request."],
+        [ :request_timeout, 408,"The server timed out waiting for the request."],
+        [ :conflict, 409, "Indicates that the request could not be processed because of conflict in the request, such as an edit conflict in the case of multiple updates."],
+        [ :precondition_failed, 412,"The server does not meet one of the preconditions that the requester put on the request."],
+        [ :unprocessable_entity, 422,"The request was well-formed but was unable to be followed due to semantic errors."],
+      ].each do |name, code, base_description|
+        api.response_template name do |media_type: nil, location: nil, headers: nil, description: nil|
+          status code
+          description( description || base_description ) # description can "potentially" be overriden in an individual action.
+
+          media_type media_type if media_type
+          location location if location
+          headers headers if headers
+        end
+      end
+
+    end
+
+
   end
 end

data/lib/praxis/responses/internal_server_error.rb

@@ -13,15 +13,16 @@ module Praxis
         @error = error
       end
 
-      def format!(exception = @error, config:)
+      def format!(exception = @error)
         if @error
-          if config.praxis.show_exceptions == true
+
+          if Application.instance.config.praxis.show_exceptions == true
             msg = {
               name: exception.class.name,
               message: exception.message,
               backtrace: exception.backtrace
             }
-            msg[:cause] = format!(exception.cause, config: config) if exception.cause
+            msg[:cause] = format!(exception.cause) if exception.cause
           else
             msg = {name: 'InternalServerError', message: "Something bad happened."}
           end
@@ -33,4 +34,12 @@ module Praxis
 
   end
 
+  ApiDefinition.define do |api|
+    api.response_template :internal_server_error do
+      description "A generic error message, given when an unexpected condition was encountered and no more specific message is suitable."
+      status 500
+      media_type "application/json"
+    end
+  end
+
 end

data/lib/praxis/responses/multipart_ok.rb

@@ -19,7 +19,7 @@ module Praxis
       end
 
 
-      def encode!(handlers:)
+      def encode!
         case @body
         when Praxis::Types::MultipartArray
           @body = @body.dump
@@ -28,9 +28,9 @@ module Praxis
         end
       end
 
-      def finish(application:)
-        format!(config: application.config)
-        encode!(handlers: application.handlers)
+      def finish
+        format!
+        encode!
 
         @body = Array(@body)
 
@@ -41,4 +41,11 @@ module Praxis
 
   end
 
+  ApiDefinition.define do |api|
+    api.response_template :multipart_ok do |media_type: Praxis::Types::MultipartArray|
+      status 200
+      media_type media_type
+    end
+  end
+
 end

data/lib/praxis/responses/validation_error.rb

@@ -15,7 +15,7 @@ module Praxis
         @documentation = documentation
       end
 
-      def format!(**_args)
+      def format!
         @body = {name: 'ValidationError', summary: @summary }
         @body[:errors] = @errors if @errors
 
@@ -31,4 +31,13 @@ module Praxis
 
   end
 
+
+  ApiDefinition.define do |api|
+    api.response_template :validation_error do
+      description "An error message indicating that one or more elements of the request did not match the API specification for the action"
+      status 400
+      media_type "application/json"
+    end
+  end
+
 end