praxis 0.17.1 → 0.18.0

data/lib/praxis/multipart/part.rb

@@ -9,6 +9,7 @@ module Praxis
     attr_accessor :payload_attribute
     attr_accessor :headers_attribute
     attr_accessor :filename_attribute
+    attr_accessor :default_handler
 
     def self.check_option!(name, definition)
       case name
@@ -76,6 +77,7 @@ module Praxis
       @name = name
       @body = body
       @headers = headers
+      @default_handler = Praxis::Application.instance.handlers['json']
 
       if content_type.nil?
         self.content_type = 'text/plain'
@@ -211,24 +213,74 @@ module Praxis
 
     def handler
       handlers = Praxis::Application.instance.handlers
-      (content_type && handlers[content_type.handler_name]) || handlers['json']
+      (content_type && handlers[content_type.handler_name]) || @default_handler
     end
 
-    def dump(**opts)
-      header_string = self.headers.collect do |name, value|
-        "#{name}: #{value}"
-      end.join("\r\n")
+    # Determine an appropriate default content_type for this part given
+    # the preferred handler_name, if possible.
+    # 
+    # Considers any pre-defined set of values on the content_type attributge
+    # of the headers.
+    def derive_content_type(handler_name)
+      possible_values = if self.content_type.match 'text/plain'
+        _, content_type_attribute = self.headers_attribute && self.headers_attribute.attributes.find { |k,v| k.to_s =~ /^content[-_]{1}type$/i }
+        if content_type_attribute && content_type_attribute.options.key?(:values)
+          content_type_attribute.options[:values]
+        else
+          []
+        end
+      else
+        [self.content_type]
+      end
+
+      # generic default encoding is the best we can do
+      if possible_values.empty?
+        return MediaTypeIdentifier.load("application/#{handler_name}")
+      end
+
+      # if any defined value match the preferred handler_name, return it
+      possible_values.each do |ct|
+        mti = MediaTypeIdentifier.load(ct)
+        return mti if mti.handler_name == handler_name
+      end
+
+      # otherwise, pick the first
+      pick = MediaTypeIdentifier.load(possible_values.first)
+
+      # and return that one if it already corresponds to a registered handler
+      # otherwise, add the encoding
+      if Praxis::Application.instance.handlers.include?(pick.handler_name)
+        return pick
+      else
+        return pick + handler_name
+      end
+
+    end
+
+    def dump(default_format: nil, **opts)
+      original_content_type = self.content_type
 
       body = self.payload_attribute.dump(self.payload, **opts)
 
       body_string = case body
       when Hash, Array
-        handler.generate(body)
+        if default_format
+          self.content_type = derive_content_type(default_format)
+        end
+
+        self.handler.generate(body)
       else
         body
       end
 
+      header_string = self.headers.collect do |name, value|
+        "#{name}: #{value}"
+      end.join("\r\n")
+
+
       "#{header_string}\r\n\r\n#{body_string}"
+    ensure
+      self.content_type = original_content_type
     end
 
   end

data/lib/praxis/request_stages/action.rb

@@ -1,13 +1,15 @@
 module Praxis
   module RequestStages
 
-    class Action < RequestStage 
-      
+    class Action < RequestStage
+
       def execute
-        if controller.method(action.name).arity == 0
-          response = controller.__send__(action.name)
-        else
-          response = controller.__send__(action.name, **request.params_hash)
+        response = Notifications.instrument 'praxis.request_stage.execute'.freeze, controller: controller do
+          if controller.method(action.name).arity == 0
+            controller.__send__(action.name)
+          else
+            controller.__send__(action.name, **request.params_hash)
+          end
         end
 
         case response
@@ -21,8 +23,8 @@ module Praxis
         controller.response.request = request
         nil # Action cannot return its OK request, as it would indicate the end of the stage chain
       end
-            
+
     end
 
   end
-end
+end

data/lib/praxis/request_stages/request_stage.rb

@@ -40,7 +40,7 @@ module Praxis
       def action
         @context.action
       end
-      
+
       def request
         @context.request
       end
@@ -111,7 +111,7 @@ module Praxis
           shortcut = stage.run
           if shortcut && shortcut.kind_of?(Praxis::Response)
             controller.response = shortcut
-            return shortcut 
+            return shortcut
           end
         end
         nil

data/lib/praxis/resource_definition.rb

@@ -60,6 +60,13 @@ module Praxis
 
       attr_accessor :controller
 
+      def display_name( string=nil )
+        unless string
+          return  @display_name ||= self.name.split("::").last  # Best guess at a display name?
+        end
+        @display_name = string
+      end
+
       def on_finalize
         if block_given?
           @on_finalize << Proc.new
@@ -268,13 +275,14 @@ module Praxis
         self.name.gsub('::'.freeze,'-'.freeze)
       end
 
-      def describe
+      def describe(context: nil)
         {}.tap do |hash|
           hash[:description] = description
-          hash[:media_type] = media_type.id if media_type
-          hash[:actions] = actions.values.map(&:describe)
+          hash[:media_type] = media_type.describe(true) if media_type
+          hash[:actions] = actions.values.collect{|action| action.describe(context: context)}
           hash[:name] = self.name
           hash[:parent] = self.parent.id if self.parent
+          hash[:display_name] = self.display_name
           hash[:metadata] = metadata
           hash[:traits] = self.traits
         end

data/lib/praxis/response_definition.rb

@@ -55,15 +55,6 @@ module Praxis
       end
     end
 
-    def example(context=nil)
-      return nil if self.media_type.nil?
-      return nil if self.media_type.kind_of?(SimpleMediaType)
-      if context.nil?
-        context = "#{self.media_type.name}-#{self.name}"
-      end
-      self.media_type.example(context)
-    end
-
     def location(loc=nil)
       return @spec[:location] if loc.nil?
       unless ( loc.is_a?(Regexp) || loc.is_a?(String) )
@@ -112,7 +103,19 @@ module Praxis
       end
     end
 
-    def describe
+    def example(context=nil)
+      return nil if self.media_type.nil?
+      return nil if self.media_type.kind_of?(SimpleMediaType)
+
+      if context.nil?
+        context = "#{self.media_type.name}-#{self.name}"
+      end
+
+      self.media_type.example(context)
+    end
+
+
+    def describe(context: nil)
       location_type = location.is_a?(Regexp) ? :regexp : :string
       location_value = location.is_a?(Regexp) ? location.inspect : location
       content = {
@@ -121,27 +124,48 @@ module Praxis
         :headers => {}
       }
       content[:location] = _describe_header(location) unless location == nil
-      # TODO: Change the mime_type key to media_type!!
-      if media_type
-        content[:media_type] = if media_type.is_a? Symbol
-          media_type
-        else
-          media_type.describe(true) # TODO: is a shallow describe what we want? or just the name?
-        end
-      end
-
-      # Generate an appropriate response example.
-      # A rendered response will need to contain not just the body of the associated media_type...
-      # but also headers, url...etc...
-      #if (media_type_example = self.example)
-      #  content[:example] = self.media_type.dump( media_type_example )
-      #end
 
       unless headers == nil
         headers.each do |name, value|
           content[:headers][name] = _describe_header(value)
         end
       end
+
+      if self.media_type
+        payload = media_type.describe(true)
+
+        if (example_payload = self.example(context))
+          payload[:examples] = {}
+          rendered_payload = example_payload.dump
+
+          # FIXME: remove load when when MediaTypeCommon.identifier returns a MediaTypeIdentifier
+          identifier = MediaTypeIdentifier.load(self.media_type.identifier)
+
+          default_handlers = ApiDefinition.instance.info.produces
+
+          handlers = Praxis::Application.instance.handlers.select do |k,v|
+            default_handlers.include?(k)
+          end
+
+          if (handler = handlers[identifier.handler_name])
+            payload[:examples][identifier.handler_name] = {
+              content_type: identifier.to_s,
+              body: handler.generate(rendered_payload)
+            }
+          else
+            handlers.each do |name, handler|
+              content_type = identifier + name
+              payload[:examples][name] = {
+                content_type: content_type.to_s,
+                body: handler.generate(rendered_payload)
+              }
+            end
+          end
+        end
+
+        content[:payload] = payload
+      end
+
       unless parts == nil
         content[:parts_like] = parts.describe
       end

data/lib/praxis/restful_doc_generator.rb

@@ -29,7 +29,13 @@ module Praxis
       the_type = the_type.type if the_type.is_a? Attributor::Attribute
 
       # Collection types are special since they wrap a member type, so let's reach in and grab it
-      the_type = the_type.member_attribute.type if the_type < Attributor::Collection
+      if the_type < Attributor::Collection
+        if the_type.member_attribute.nil?
+          the_type = the_type.member_type
+        else
+          the_type = the_type.member_attribute.type 
+        end
+      end
 
       if @inspected_types.include? the_type
         # We're done if we've already inspected it
@@ -134,6 +140,8 @@ module Praxis
       @doc_root_dir = File.join(@root_dir, API_DOCS_DIRNAME)
       @resources = []
 
+      Attributor::AttributeResolver.current = Attributor::AttributeResolver.new
+      
       remove_previous_doc_data
       load_resources
 

data/lib/praxis/route.rb

@@ -12,6 +12,22 @@ module Praxis
       @prefixed_path = prefixed_path
     end
 
+    def example(example_hash:{}, params:)
+      path_param_keys = self.path.named_captures.keys.collect(&:to_sym)
+
+      param_attributes = params ? params.attributes : {}
+      query_param_keys = param_attributes.keys - path_param_keys
+      required_query_param_keys = query_param_keys.each_with_object([]) do |p, array|
+        array << p if params.attributes[p].options[:required]
+      end
+
+      path_params = example_hash.select{|k,v| path_param_keys.include? k }
+      # Let's generate the example only using required params, to avoid mixing incompatible parameters
+      query_params = example_hash.select{|k,v| required_query_param_keys.include? k }
+      example = { verb: self.verb, url: self.path.expand(path_params), query_params: query_params }
+
+    end
+
     def describe
       result = {
         verb: verb,

data/lib/praxis/router.rb

@@ -95,7 +95,7 @@ module Praxis
           body += if version == 'n/a'
             ". Your request did not specify an API version.".freeze
           else
-            ". Your request speficied API version = \"#{version}\"."
+            ". Your request specified API version = \"#{version}\"."
           end
           pretty_versions = attempted_versions.collect(&:inspect).join(', ')
           body += " Available versions = #{pretty_versions}."

data/lib/praxis/simple_media_type.rb

@@ -9,7 +9,7 @@ module Praxis
     def name
       self.class.name
     end
-    
+
     def id
       self.class.name.gsub("::",'-')
     end
@@ -17,6 +17,7 @@ module Praxis
     def describe(shallow=true)
       {identifier: identifier}
     end
+
   end
 
 end

data/lib/praxis/tasks/api_docs.rb

@@ -27,7 +27,7 @@ namespace :praxis do
     end
 
     desc "Run API Documentation Browser"
-    task :preview, [:port] => [:install, :generate]  do |t, args|      
+    task :preview, [:port] => [:install, :generate]  do |t, args|
       doc_port = args[:port] || '9090'
       exec({'USER_DOCS_PATH' => File.join(Dir.pwd, 'docs'), 'DOC_PORT' => doc_port}, "#{path}/node_modules/.bin/grunt serve --gruntfile '#{path}/Gruntfile.js'")
     end
@@ -45,6 +45,15 @@ namespace :praxis do
       generator = Praxis::RestfulDocGenerator.new(Dir.pwd)
     end
 
+    desc "Generate BETA API docs (JSON definitions) for a Praxis App"
+    task :generate_beta => [:environment] do |t, args|
+      require 'fileutils'
+
+      Praxis::Blueprint.caching_enabled = false
+      generator = Praxis::Docs::Generator.new(Dir.pwd)
+      generator.save!
+    end
+
   end
 
   desc "Generate API docs (JSON definitions) for a Praxis App"

data/lib/praxis/tasks/console.rb

@@ -11,7 +11,6 @@ namespace :praxis do
     rescue LoadError
       # Fall back on irb
       require 'irb'
-      require 'irb/ext/multi-irb'
     end
 
     Rake::Task['praxis:environment'].invoke
@@ -19,10 +18,18 @@ namespace :praxis do
     if have_pry
       Praxis::Application.instance.pry
     else
-      # Use some special initialization magic to ensure that 'self' in the
-      # IRB session refers to Praxis::Application.instance.
+      # Keep IRB.setup from complaining about bad ARGV options
+      old_argv = ARGV.dup
+      ARGV.clear
       IRB.setup nil
+      ARGV.concat(old_argv)
+
+      # Allow reentrant IRB
       IRB.conf[:MAIN_CONTEXT] = IRB::Irb.new.context
+      require 'irb/ext/multi-irb'
+
+      # Use some special initialization magic to ensure that 'self' in the
+      # IRB session refers to Praxis::Application.instance.
       IRB.irb(nil, Praxis::Application.instance)
     end
   end

data/lib/praxis/types/media_type_common.rb

@@ -9,7 +9,7 @@ module Praxis
         def describe(shallow = false, **opts)
           hash = super
           unless shallow
-            hash.merge!(identifier: @identifier.to_s, description: @description)
+            hash.merge!(identifier: @identifier.to_s, description: @description, display_name: self.display_name)
           end
           hash
         end
@@ -19,6 +19,13 @@ module Praxis
           @description
         end
 
+        def display_name( string=nil )
+          unless string
+            return  @display_name ||= self.name.split("::").last  # Best guess at a display name?
+          end
+          @display_name = string
+        end
+
         # Get or set the identifier of this media type.
         #
         # @deprecated this method is not deprecated, but its return type will change to MediaTypeIdentifier in Praxis 1.0

data/lib/praxis/types/multipart.rb

@@ -98,6 +98,11 @@ module Praxis
       super
     end
 
+    def self.describe(shallow = false, **opts)
+      hash = super(**opts)
+      hash.merge!(family: 'multipart')
+      hash
+    end
   end
 
 

data/lib/praxis/types/multipart_array.rb

@@ -52,8 +52,13 @@ module Praxis
       end
 
       def self.payload_type(type=nil, **opts, &block)
-        return @payload_type if type.nil?
-
+        if type.nil?
+          if block_given?
+            type = Attributor::Struct
+          else
+            return @payload_type
+          end
+        end
         @payload_type = Attributor.resolve_type(type)
         @payload_attribute = Attributor::Attribute.new(@payload_type, **opts, &block)
         @part_attribute = nil
@@ -188,7 +193,7 @@ module Praxis
           end
 
           sub_hash = part_attribute.describe(shallow, example: sub_example)
-          
+
 
           if (options = sub_hash.delete(:options))
             sub_hash[:options] = {}
@@ -204,7 +209,7 @@ module Praxis
           end
 
           sub_hash[:type] = MultipartPart.describe(shallow, example: sub_example, options: part_attribute.options)
-          
+
 
           parts[part_name] = sub_hash
         end
@@ -302,6 +307,9 @@ module Praxis
         errors
       end
 
+      def self.dump(value, **opts)
+        value.dump(**opts)
+      end
 
       def dump(**opts)
         boundary = content_type.parameters.get 'boundary'

data/lib/praxis/version.rb

@@ -1,3 +1,3 @@
 module Praxis
-  VERSION = '0.17.1'
+  VERSION = '0.18.0'
 end

data/lib/praxis.rb

@@ -47,6 +47,9 @@ module Praxis
   autoload :Notifications, 'praxis/notifications'
 
   autoload :RestfulDocGenerator, 'praxis/restful_doc_generator'
+  module Docs
+    autoload :Generator, 'praxis/docs/generator'
+  end
 
   # types
   module Types

data/praxis.gemspec

@@ -24,9 +24,9 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'mustermann', '~> 0'
   spec.add_dependency 'activesupport', '>= 3'
   spec.add_dependency 'mime', '~> 0'
-  spec.add_dependency 'praxis-mapper', '>= 4.0.0'
-  spec.add_dependency 'praxis-blueprints', '>= 2.0.0'
-  spec.add_dependency 'attributor', '>= 4.0.0'
+  spec.add_dependency 'praxis-mapper', '>= 4.1'
+  spec.add_dependency 'praxis-blueprints', '>= 2.2'
+  spec.add_dependency 'attributor', '>= 4.0.1'
   spec.add_dependency 'thor', '~> 0.18'
   spec.add_dependency 'terminal-table', '~> 1.4'
   spec.add_dependency 'harness', '~> 2'

data/spec/functional_spec.rb

@@ -268,7 +268,7 @@ describe 'Functional specs' do
 
 
   context 'not found and API versions' do
-    context 'when no version is speficied' do
+    context 'when no version is specified' do
       it 'it tells you which available api versions would match' do
         get '/api/clouds/1/instances/2?junk=foo',nil, 'global_session' => session
 
@@ -285,13 +285,13 @@ describe 'Functional specs' do
       end
     end
 
-    context 'when some version is speficied, but wrong' do
+    context 'when some version is specified, but wrong' do
       it 'it tells you which possible correcte api versions exist' do
         get '/api/clouds/1/instances/2?junk=foo&api_version=50.0', nil, 'global_session' => session
 
         expect(last_response.status).to eq(404)
         expect(last_response.headers["Content-Type"]).to eq("text/plain")
-        expect(last_response.body).to eq("NotFound. Your request speficied API version = \"50.0\". Available versions = \"1.0\".")
+        expect(last_response.body).to eq("NotFound. Your request specified API version = \"50.0\". Available versions = \"1.0\".")
       end
     end
 

data/spec/praxis/action_definition_spec.rb

@@ -100,6 +100,10 @@ describe Praxis::ActionDefinition do
   end
 
   describe '#params' do
+    it 'defaults to being required if omitted' do
+      expect(subject.params.options[:required]).to be(true)
+    end
+
     it 'merges in more params' do
       subject.params do
         attribute :more, Attributor::Integer
@@ -108,9 +112,22 @@ describe Praxis::ActionDefinition do
       attributes = subject.params.attributes.keys
       expect(attributes).to match_array([:one, :inherited, :more])
     end
+
+    it 'merges options (which allows overriding)' do
+      expect(subject.params.options[:required]).to be(true)
+
+      subject.params required: false
+
+      expect(subject.params.options[:required]).to be(false)
+    end
   end
 
   describe '#payload' do
+    it 'defaults to being required if omitted' do
+      expect(subject.payload.options[:required]).to be(true)
+    end
+
+
     it 'merges in more payload' do
       subject.payload do
         attribute :more, Attributor::Integer
@@ -120,6 +137,14 @@ describe Praxis::ActionDefinition do
                                                                :two, :inherited, :more
       ])
     end
+
+    it 'merges options (which allows overriding)' do
+      expect(subject.payload.options[:required]).to be(true)
+
+      subject.payload required: false
+
+      expect(subject.payload.options[:required]).to be(false)
+    end
   end
 
   describe '#headers' do
@@ -131,6 +156,10 @@ describe Praxis::ActionDefinition do
       expect(subject.headers.type.options[:case_insensitive_load]).to be(true)
     end
 
+    it 'defaults to being required if omitted' do
+      expect(subject.headers.options[:required]).to be(true)
+    end
+
     it 'merges in more headers' do
       subject.headers do
         header "more"
@@ -139,6 +168,16 @@ describe Praxis::ActionDefinition do
       expected_array = ["X_REQUESTED_WITH", "Inherited", "more"]
       expect(subject.headers.attributes.keys).to match_array(expected_array)
     end
+
+    it 'merges options (which allows overriding)' do
+      expect(subject.headers.options[:required]).to be(true)
+
+      subject.headers required: false do
+        header "even_more"
+      end
+
+      expect(subject.headers.options[:required]).to be(false)
+    end
   end
 
   context '#routing' do
@@ -187,6 +226,7 @@ describe Praxis::ActionDefinition do
         expect(attributes[:one][:source]).to eq('url')
       end
     end
+
   end
 
   context 'href generation' do

data/spec/praxis/api_general_info_spec.rb

@@ -16,6 +16,10 @@ describe Praxis::ApiGeneralInfo do
       description "Description"
       endpoint 'api.example.com'
       base_path "/base"
+
+      consumes 'xml', 'x-www-form-urlencoded'
+      produces 'json', 'x-www-form-urlencoded'
+
       base_params do
         attribute :name, String
       end
@@ -36,8 +40,10 @@ describe Praxis::ApiGeneralInfo do
     end
 
     its(:name) { should eq 'Name' }
-
+    its(:consumes) { should eq ['xml', 'x-www-form-urlencoded']}
+    its(:produces) { should eq ['json', 'x-www-form-urlencoded']}
   end
+
   context '.describe' do
     before do
       info.instance_exec &info_block
@@ -53,6 +59,8 @@ describe Praxis::ApiGeneralInfo do
     its([:base_params, :name, :type, :name]) { should eq 'String' }
     its([:version_with]) { should eq([:header, :params]) }
     its([:endpoint]) { should eq 'api.example.com' }
+    its([:consumes]) { should eq ['xml', 'x-www-form-urlencoded'] }
+    its([:produces]) { should eq ['json', 'x-www-form-urlencoded'] }
   end
 
   context 'base_path with versioning' do
@@ -66,8 +74,7 @@ describe Praxis::ApiGeneralInfo do
 
       global_info.version_with :path
       global_info.base_path '/api/v:api_version'
-    end
-    
+    end    
 
     its(:base_path) { should eq '/api/v1.0'}
   end