praxis 0.13.0 → 0.14.0

data/lib/praxis/links.rb

@@ -58,7 +58,7 @@ module Praxis
       end
     end
 
-    def self.define_blueprint_reader!(name)
+    def self.define_reader!(name)
       # it's faster to use define_method in this case than module_eval
       # because we save the attribute lookup on every access.
       attribute = self.attributes[name]
@@ -79,12 +79,6 @@ module Praxis
             self.__send__(name)
           end
         end
-
-        @reference.attribute.type.instance_eval do
-          define_method(using) do
-            self.__send__(name)
-          end
-        end
       end
 
     end
@@ -103,7 +97,7 @@ module Praxis
     # This is primarily necessary only for example generation.
     def self.fixup_reference_struct_methods
       self.links.each do |name, using|
-        next if @reference.attribute.attributes.has_key?(name)
+        next if @reference.attribute.attributes.has_key?(using)
         @reference.attribute.type.instance_eval do
           define_method(using) do
             return nil unless attributes[:links]

data/lib/praxis/media_type.rb

@@ -1,5 +1,6 @@
 module Praxis
   class MediaType < Praxis::Blueprint
+    include Types::MediaTypeCommon
 
     class DSLCompiler < Attributor::DSLCompiler
       def links(&block)
@@ -7,25 +8,6 @@ module Praxis
       end
     end
 
-    def self.description(text=nil)
-      @description = text if text
-      @description
-    end
-
-    def self.identifier(identifier=nil)
-      return @identifier unless identifier
-      # TODO: parse the string and extract things like collection , and format type?...
-      @identifier = identifier
-    end
-
-    def self.describe(shallow = false)
-      hash = super
-      unless shallow
-        hash.merge!(identifier: @identifier, description: @description)
-      end
-      hash
-    end
-
     def self.attributes(opts={}, &block)
       super(opts.merge(dsl_compiler: MediaType::DSLCompiler), &block)
     end
@@ -34,16 +16,16 @@ module Praxis
       super
       if @attribute && self.attributes.key?(:links) && self.attributes[:links].type < Praxis::Links
         # Only define out special links accessor if it was setup using the special DSL
-        # (we might have an app defining an attribute called `links` on its own, in which 
+        # (we might have an app defining an attribute called `links` on its own, in which
         # case we leave it be)
         module_eval <<-RUBY, __FILE__, __LINE__ + 1
-          def links
-            self.class::Links.new(@object)
-          end
+        def links
+          self.class::Links.new(@object)
+        end
         RUBY
       end
     end
-
+    
   end
 
 end

data/lib/praxis/media_type_collection.rb

@@ -26,7 +26,12 @@ module Praxis
     class << self
       attr_accessor :member_attribute
     end
-    
+
+    def self.inherited(klass)
+      warn "DEPRECATION: MediaTypeCollection is deprecated and will be removed by 1.0"
+      super
+    end
+
     def self._finalize!
       super
 
@@ -35,7 +40,6 @@ module Praxis
           include StructCollection
         end
       end
-
     end
 
     def self.member_type(type=nil)

data/lib/praxis/plugin_concern.rb

@@ -12,7 +12,8 @@ module Praxis
         :Request,
         :Controller,
         :ResourceDefinition,
-        :ActionDefinition
+        :ActionDefinition,
+        :Response
       ]
 
       def setup!

data/lib/praxis/request.rb

@@ -4,15 +4,25 @@ module Praxis
     attr_reader :env, :query
     attr_accessor :route_params, :action
 
+    PATH_VERSION_PREFIX = "/v".freeze
+    CONTENT_TYPE_NAME = 'CONTENT_TYPE'.freeze
+    PATH_INFO_NAME = 'PATH_INFO'.freeze
+    REQUEST_METHOD_NAME = 'REQUEST_METHOD'.freeze
+    QUERY_STRING_NAME = 'QUERY_STRING'.freeze
+    API_VERSION_HEADER_NAME = "HTTP_X_API_VERSION".freeze
+    API_VERSION_PARAM_NAME = 'api_version'.freeze
+    API_NO_VERSION_NAME = 'n/a'.freeze
+    VERSION_USING_DEFAULTS = [:header,:params].freeze
+    
     def initialize(env)
       @env = env
-      @query = Rack::Utils.parse_nested_query(env['QUERY_STRING'.freeze])
+      @query = Rack::Utils.parse_nested_query(env[QUERY_STRING_NAME])
       @route_params = {}
       @path_version_matcher = path_version_matcher
     end
 
     def content_type
-      @env['CONTENT_TYPE'.freeze]
+      @env[CONTENT_TYPE_NAME]
     end
 
     # The media type (type/subtype) portion of the CONTENT_TYPE header
@@ -26,27 +36,24 @@ module Praxis
     end
 
     def path
-      @env['PATH_INFO'.freeze]
+      @env[PATH_INFO_NAME]
     end
 
     attr_accessor :headers, :params, :payload
 
     def params_hash
       return {} if params.nil?
-
-      params.attributes.each_with_object({}) do |(k,v),hash|
-        hash[k] = v
-      end
+      params.attributes
     end
 
     def verb
-      @env['REQUEST_METHOD'.freeze]
+      @env[REQUEST_METHOD_NAME]
     end
 
     def raw_params
       @raw_params ||= begin
         params = query.merge(route_params)
-        params.delete('api_version'.freeze)
+        params.delete(API_VERSION_PARAM_NAME)
         params
       end
     end
@@ -66,21 +73,23 @@ module Praxis
     end
     
     def self.path_version_prefix
-      "/v".freeze
+      PATH_VERSION_PREFIX
     end
+
+    PATH_VERSION_MATCHER = %r{^#{self.path_version_prefix}(?<version>[^\/]+)\/}.freeze
     
     def path_version_matcher
-      %r{^#{Request.path_version_prefix}(?<version>[^\/]+)\/}.freeze
+      PATH_VERSION_MATCHER
     end
     
-    def version(using: [:header,:params].freeze)
+    def version(using: VERSION_USING_DEFAULTS )
       result = nil
       Array(using).find do |mode|
         case mode
         when :header ;
-          result = env["HTTP_X_API_VERSION".freeze]
+          result = env[API_VERSION_HEADER_NAME]
         when :params ;
-          result = @query['api_version'.freeze]
+          result = @query[API_VERSION_PARAM_NAME]
         when :path ;
           m = self.path.match(@path_version_matcher) 
           result = m[:version] unless m.nil?
@@ -88,7 +97,7 @@ module Praxis
           raise "Unknown method for retrieving the API version: #{mode}"
         end
       end
-      return result || 'n/a'.freeze
+      return result || API_NO_VERSION_NAME
     end
 
     def load_headers(context)

data/lib/praxis/request_stages/request_stage.rb

@@ -7,11 +7,10 @@ module Praxis
     class RequestStage < Stage
       extend Forwardable
 
-      def_delegators :@context, :controller, :action, :request
       alias :dispatcher :application # it's technically application in the base Stage
 
       def path
-        [name]
+        @the_path ||= [name].freeze
       end
 
       def execute_controller_callbacks(callbacks)
@@ -31,9 +30,25 @@ module Praxis
         nil
       end
 
-      def run
-        setup!
+      def setup!
         setup_deferred_callbacks!
+      end
+
+      # Avoid using delegators, and create the explicit functions:
+      # def_delegators :@context, :controller, :action, :request
+      # they allocate all kinds of things and we don't need the generality here
+      def controller
+        @context.controller
+      end
+      def action
+        @context.action
+      end
+      def request
+        @context.request
+      end
+
+      
+      def run
 
         # stage-level callbacks (typically empty) will never shortcut
         execute_callbacks(self.before_callbacks)

data/lib/praxis/request_stages/validate_params_and_headers.rb

@@ -11,7 +11,7 @@ module Praxis
 
 
       def path
-        @parent.path + [name]
+        @_path ||= ( @parent.path + [name] )
       end
 
       def execute

data/lib/praxis/request_stages/validate_payload.rb

@@ -11,7 +11,7 @@ module Praxis
       end
 
       def path
-        @parent.path + [name]
+        @_path ||= ( @parent.path + [name] )
       end
 
       def execute

data/lib/praxis/resource_definition.rb

@@ -1,11 +1,11 @@
 require 'active_support/concern'
 require 'active_support/inflector'
 
-
 module Praxis
   module ResourceDefinition
     extend ActiveSupport::Concern
-
+    DEFAULT_RESOURCE_HREF_ACTION = :show
+    
     included do
       @version = 'n/a'.freeze
       @actions = Hash.new
@@ -21,7 +21,7 @@ module Praxis
       attr_reader :routing_config
       attr_reader :responses
       attr_reader :version_options
-  
+
       # opaque hash of user-defined medata, used to decorate the definition,
       # and also available in the generated JSON documents
       attr_reader :metadata
@@ -42,24 +42,55 @@ module Praxis
         @media_type = media_type
       end
 
-      def version(version=nil, options= { using: [:header,:params] }.freeze )
+      def version(version=nil, options=nil)
         return @version unless version
         @version = version
-        @version_options = options
+        @version_options = options || {using: [:header,:params]}
+      end
+
+      def canonical_path( action_name=nil )
+        if action_name
+          raise "Canonical path for #{self.name} is already defined as: '#{@canonical_action_name}'. 'canonical_path' can only be defined once." if @canonical_action_name
+          @canonical_action_name = action_name
+        else
+          # Resolution of the actual action definition needs to be done lazily, since we can use the `canonical_path` stanza
+          # at the top of the resource, well before the actual action is defined.
+          unless @canonical_action
+            href_action = @canonical_action_name || DEFAULT_RESOURCE_HREF_ACTION
+            @canonical_action = actions.fetch(href_action) do
+              raise "Error: trying to set canonical_href of #{self.name}. Action '#{href_action}' does not exist"
+            end
+          end
+          return @canonical_action
+        end
+      end
+      
+      def to_href( params )
+        canonical_path.primary_route.path.expand(params)
       end
 
+      def parse_href(path)
+        param_values = canonical_path.primary_route.path.params(path)
+        attrs = canonical_path.params.attributes
+        param_values.each_with_object({}) do |(key,value),hash|
+          hash[key.to_sym] = attrs[key.to_sym].load(value,[key])
+        end
+      rescue => e
+        raise Praxis::Exception.new("Error parsing or coercing parameters from href: #{path}\n"+e.message)
+      end
+      
       def action_defaults(&block)
         return @action_defaults unless block_given?
 
         @action_defaults << block
       end
-  
+
       def params(type=Attributor::Struct, **opts, &block)
         warn 'DEPRECATION: ResourceDefinition.params is deprecated. Use it in action_defaults instead.'
         action_defaults do
           params type, **opts, &block
         end
-      end      
+      end
 
       def payload(type=Attributor::Struct, **opts, &block)
         warn 'DEPRECATION: ResourceDefinition.payload is deprecated. Use action_defaults instead.'
@@ -74,7 +105,7 @@ module Praxis
           headers **opts, &block
         end
       end
-      
+
       def response(name, **args)
         warn 'DEPRECATION: ResourceDefinition.response is deprecated. Use action_defaults instead.'
         action_defaults do
@@ -84,6 +115,7 @@ module Praxis
 
       def action(name, &block)
         raise ArgumentError, "can not create ActionDefinition without block" unless block_given?
+        raise ArgumentError, "Action names must be defined using symbols (Got: #{name} (of type #{name.class}))" unless name.is_a? Symbol
         @actions[name] = ActionDefinition.new(name, self, &block)
       end
 
@@ -92,13 +124,16 @@ module Praxis
         @description
       end
 
-    
+      def id
+        self.name.gsub('::'.freeze,'-'.freeze)
+      end
 
       def describe
         {}.tap do |hash|
           hash[:description] = description
-          hash[:media_type] = media_type.name if media_type
+          hash[:media_type] = media_type.id if media_type
           hash[:actions] = actions.values.map(&:describe)
+          hash[:name] = self.name 
           hash[:metadata] = metadata
         end
       end

data/lib/praxis/response_definition.rb

@@ -36,23 +36,23 @@ module Praxis
       return @spec[:media_type] if media_type.nil?
 
       @spec[:media_type] = case media_type
-        when String
-          SimpleMediaType.new(media_type)
-        when Class
-          if media_type < Praxis::MediaType
-            media_type
-          else
-            raise Exceptions::InvalidConfiguration.new(
-              'Invalid media_type specification. media_type must be a Praxis::MediaType'
-            )
-          end
-        when SimpleMediaType
+      when String
+        SimpleMediaType.new(media_type)
+      when Class
+        if media_type < Praxis::Types::MediaTypeCommon
           media_type
         else
           raise Exceptions::InvalidConfiguration.new(
-            'Invalid media_type specification. media_type must be a String, MediaType or SimpleMediaType'
+            'Invalid media_type specification. media_type must be a Praxis::MediaType'
           )
         end
+      when SimpleMediaType
+        media_type
+      else
+        raise Exceptions::InvalidConfiguration.new(
+          'Invalid media_type specification. media_type must be a String, MediaType or SimpleMediaType'
+        )
+      end
     end
 
     def location(loc=nil)
@@ -94,11 +94,11 @@ module Praxis
             )
           end
           @spec[:headers][k] = v
-       end
+        end
       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 Hash (to match both the name and the value). Received: #{hdr.inspect}"
         )
       end
     end
@@ -122,7 +122,7 @@ module Praxis
       end
       unless headers == nil
         headers.each do |name, value|
-          content[:headers][name] = _describe_header(value) 
+          content[:headers][name] = _describe_header(value)
         end
       end
       unless parts == nil
@@ -134,7 +134,7 @@ module Praxis
     def _describe_header(data)
       data_type = data.is_a?(Regexp) ? :regexp : :string
       data_value = data.is_a?(Regexp) ? data.inspect : data
-       { :value => data_value, :type => data_type } 
+      { :value => data_value, :type => data_type }
     end
 
     def validate( response )
@@ -151,15 +151,15 @@ module Praxis
         raise ArgumentError, "Parts definition for response #{name} needs a :like argument or a block/proc" if !args.empty?
         return @parts
       end
-       if like && a_proc
+      if like && a_proc
         raise ArgumentError, "Parts definition for response #{name} does not allow :like and a block simultaneously"
       end
       if like
-         template = ApiDefinition.instance.response(like)
-         @parts = template.compile(nil, **args)
-       else # block
-         @parts = Praxis::ResponseDefinition.new('anonymous', **args, &a_proc)
-       end
+        template = ApiDefinition.instance.response(like)
+        @parts = template.compile(nil, **args)
+      else # block
+        @parts = Praxis::ResponseDefinition.new('anonymous', **args, &a_proc)
+      end
     end
 
     # Validates Status code
@@ -238,17 +238,36 @@ module Praxis
     def validate_content_type!(response)
       return unless media_type
 
-      extracted_identifier = nil
+      response_content_type = {}
       if response.headers['Content-Type']
-        extracted_identifier = Praxis::ContentTypeParser.parse(response.headers['Content-Type'])[:type]
+        response_content_type = Praxis::ContentTypeParser.parse(response.headers['Content-Type'])
       end
 
-      if media_type.identifier != extracted_identifier
+      expected_content_type = Praxis::ContentTypeParser.parse(media_type.identifier)
+
+      unless response_content_type[:type] == expected_content_type[:type]
         raise Exceptions::Validation.new(
-          "Bad Content-Type header. Returned type #{extracted_identifier}" +
-          " does not match type #{media_type.identifier} as described in response: #{self.name}"
+          "Bad Content-Type header. #{response.headers['Content-Type']}" +
+          " does not match type #{expected_content_type[:type]} as described in response: #{self.name}"
         )
       end
+
+      if (expected_params = expected_content_type[:params])
+        expected_params.each do |param_name,expected_param|
+          response_param = response_content_type[:params].fetch(param_name) do
+            raise Exceptions::Validation.new(
+              "Bad Content-Type header: #{response.headers['Content-Type']}" +
+              " does not contain expected param '#{param_name}' as described in response: #{self.name}"
+            )
+          end
+          unless response_param == expected_param
+            raise Exceptions::Validation.new(
+              "Bad Content-Type header: #{response.headers['Content-Type']}" +
+              " param: #{param_name} does not match expected value #{expected_param} as described in response: #{self.name}"
+            )
+          end
+        end
+      end
     end
 
     def validate_parts!(response)