praxis 0.14.0 → 0.15.0

data/lib/praxis/request.rb

@@ -12,8 +12,8 @@ module Praxis
     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
-    
+    VERSION_USING_DEFAULTS = [:header, :params].freeze
+
     def initialize(env)
       @env = env
       @query = Rack::Utils.parse_nested_query(env[QUERY_STRING_NAME])
@@ -21,18 +21,25 @@ module Praxis
       @path_version_matcher = path_version_matcher
     end
 
+    # Determine the content type of this request as indicated by the Content-Type header.
+    #
+    # @return [nil,MediaTypeIdentifier] nil if the header is missing, else a media-type identifier
     def content_type
-      @env[CONTENT_TYPE_NAME]
+      header = @env[CONTENT_TYPE_NAME]
+      @content_type ||= (header && MediaTypeIdentifier.load(header)).freeze
     end
 
-    # The media type (type/subtype) portion of the CONTENT_TYPE header
-    # without any media type parameters. e.g., when CONTENT_TYPE is
-    # "text/plain;charset=utf-8", the media-type is "text/plain".
+    # The media type (type/subtype+suffix) portion of the Content-Type
+    # header without any media type parameters. e.g., when Content-Type
+    # is "text/plain;charset=utf-8", the media-type is "text/plain".
     #
     # For more information on the use of media types in HTTP, see:
     # http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7
+    #
+    # @return [String]
+    # @see MediaTypeIdentifier#without_parameters
     def media_type
-      content_type && content_type.split(/\s*[;,]\s*/, 2).first.downcase
+      content_type.without_parameters.to_s
     end
 
     def path
@@ -71,27 +78,27 @@ module Praxis
       self.raw_params
       self.raw_payload
     end
-    
+
     def self.path_version_prefix
       PATH_VERSION_PREFIX
     end
 
     PATH_VERSION_MATCHER = %r{^#{self.path_version_prefix}(?<version>[^\/]+)\/}.freeze
-    
+
     def path_version_matcher
       PATH_VERSION_MATCHER
     end
-    
-    def version(using: VERSION_USING_DEFAULTS )
+
+    def version(using: VERSION_USING_DEFAULTS)
       result = nil
       Array(using).find do |mode|
         case mode
-        when :header ;
+        when :header;
           result = env[API_VERSION_HEADER_NAME]
-        when :params ;
+        when :params;
           result = @query[API_VERSION_PARAM_NAME]
-        when :path ;
-          m = self.path.match(@path_version_matcher) 
+        when :path;
+          m = self.path.match(@path_version_matcher)
           result = m[:version] unless m.nil?
         else
           raise "Unknown method for retrieving the API version: #{mode}"
@@ -102,7 +109,7 @@ module Praxis
 
     def load_headers(context)
       return unless action.headers
-      defined_headers = action.precomputed_header_keys_for_rack.each_with_object(Hash.new) do |(upper,original), hash|
+      defined_headers = action.precomputed_header_keys_for_rack.each_with_object(Hash.new) do |(upper, original), hash|
         hash[original] = self.env[upper] if self.env.has_key? upper
       end
       self.headers = action.headers.load(defined_headers, context)
@@ -115,16 +122,18 @@ module Praxis
 
     def load_payload(context)
       return unless action.payload
-      raw = case content_type
-        when %r|^application/x-www-form-urlencoded|i
-          Rack::Utils.parse_nested_query(self.raw_payload)
-        when nil
-          {}
-        else
-          self.raw_payload
-        end
+      return if content_type.nil?
+
+      handler = Praxis::Application.instance.handlers[content_type.handler_name]
+
+      if handler
+        raw = handler.parse(self.raw_payload)
+      else
+        # TODO is this a good default?
+        raw = self.raw_payload
+      end
 
-      self.payload = action.payload.load(raw, context, content_type: content_type)
+      self.payload = action.payload.load(raw, context, content_type: content_type.to_s)
     end
 
     def validate_headers(context)

data/lib/praxis/response.rb

@@ -1,7 +1,5 @@
 module Praxis
   class Response
-
-
     attr_reader :name
     attr_reader :parts
 
@@ -29,6 +27,22 @@ module Praxis
       @parts = Hash.new
     end
 
+    # Determine the content type of this response.
+    #
+    # @return [MediaTypeIdentifier]
+    def content_type
+      MediaTypeIdentifier.load(headers['Content-Type']).freeze
+    end
+
+    # Set the content type for this response.
+    # @todo DRY this out (also used in Multipart::Part)
+    #
+    # @return [String]
+    # @param [String,MediaTypeIdentifier] identifier
+    def content_type=(identifier)
+      headers['Content-Type'] = MediaTypeIdentifier.load(identifier).to_s
+    end
+
     def handle
     end
 
@@ -54,7 +68,12 @@ module Praxis
     def encode!
       case @body
       when Hash, Array
-        @body = JSON.pretty_generate(@body)
+        # 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
 

data/lib/praxis/response_definition.rb

@@ -210,19 +210,15 @@ module Praxis
         case value
         when String
           if response.headers[name] != value
-            unless valid
-              raise Exceptions::Validation.new(
-                "Header #{name.inspect}, with value #{value.inspect} does not match #{response.headers[name]}."
-              )
-            end
+            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
-            unless valid
-              raise Exceptions::Validation.new(
-                "Header #{name.inspect}, with value #{value.inspect} does not match #{response.headers[name].inspect}."
-              )
-            end
+            raise Exceptions::Validation.new(
+              "Header #{name.inspect}, with value #{value.inspect} does not match #{response.headers[name].inspect}."
+            )
           end
         end
       end
@@ -238,36 +234,15 @@ module Praxis
     def validate_content_type!(response)
       return unless media_type
 
-      response_content_type = {}
-      if response.headers['Content-Type']
-        response_content_type = Praxis::ContentTypeParser.parse(response.headers['Content-Type'])
-      end
-
-      expected_content_type = Praxis::ContentTypeParser.parse(media_type.identifier)
+      response_content_type = response.content_type
+      expected_content_type = Praxis::MediaTypeIdentifier.load(media_type.identifier)
 
-      unless response_content_type[:type] == expected_content_type[:type]
+      unless expected_content_type.match(response_content_type)
         raise Exceptions::Validation.new(
-          "Bad Content-Type header. #{response.headers['Content-Type']}" +
-          " does not match type #{expected_content_type[:type]} as described in response: #{self.name}"
+          "Bad Content-Type header. #{response_content_type}" +
+          " is incompatible with #{expected_content_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)

data/lib/praxis/restful_doc_generator.rb

@@ -226,7 +226,7 @@ module Praxis
             type_output[:example] = if example_data.respond_to? :render
               example_data.render(:master)
             else
-              example_data.dump
+              type.dump(example_data)
             end
           end
 

data/lib/praxis/simple_media_type.rb

@@ -1,5 +1,10 @@
 module Praxis
-  
+
+  # Stripped-down representation of an Internet Media Type where the structure and content of the
+  # type are unknown, or are defined externally to the Praxis application.
+  #
+  # @see Praxis::MediaType
+  # @see Praxis::Types::MediaTypeCommon
   SimpleMediaType = Struct.new(:identifier) do
     def name
       self.class.name

data/lib/praxis/types/media_type_common.rb

@@ -1,6 +1,7 @@
 module Praxis
   module Types
 
+    # Traits that are shared by MediaType and SimpleMediaType.
     module MediaTypeCommon
       extend ::ActiveSupport::Concern
 
@@ -18,10 +19,14 @@ module Praxis
           @description
         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
+        #
+        # @return [String] the string-representation of this type's identifier
         def identifier(identifier=nil)
-          return @identifier unless identifier
-          # TODO: parse the string and extract things like collection , and format type?...
-          @identifier = identifier
+          return @identifier.to_s unless identifier
+          (@identifier = MediaTypeIdentifier.load(identifier)).to_s
         end
       end
 

data/lib/praxis/types/multipart.rb

@@ -4,11 +4,14 @@ module Praxis
 
     @key_type = Attributor::String
 
-    def self.load(value, context=Attributor::DEFAULT_ROOT_CONTEXT, content_type:)
-      #return super if content_type.nil?
+    def self.load(value, context=Attributor::DEFAULT_ROOT_CONTEXT, content_type:nil)
+      return value if value.kind_of?(self) || value.nil?
 
+      unless (value.kind_of?(::String) && ! content_type.nil?)
+        raise Attributor::CoercionError, context: context, from: value.class, to: self.name, value: value
+      end 
+      
       headers = {'Content-Type' => content_type}
-
       parser = MultipartParser.new(headers, value)
       preamble, parts = parser.parse
 
@@ -60,9 +63,6 @@ module Praxis
       super
     end
 
-    #def []=(k, v)
-    #end
-
   end
 
 

data/lib/praxis/version.rb

@@ -1,3 +1,3 @@
 module Praxis
-  VERSION = '0.14.0'
+  VERSION = '0.15.0'
 end

data/lib/praxis.rb

@@ -50,7 +50,6 @@ module Praxis
   autoload :Router, 'praxis/router'
   autoload :SimpleMediaType, 'praxis/simple_media_type'
   autoload :Stage, 'praxis/stage'
-  autoload :ContentTypeParser, 'praxis/content_type_parser'
 
   autoload :Stats, 'praxis/stats'
   autoload :Notifications, 'praxis/notifications'
@@ -65,6 +64,7 @@ module Praxis
   autoload :Links, 'praxis/links'
   autoload :MediaType, 'praxis/media_type'
   autoload :MediaTypeCollection, 'praxis/media_type_collection'
+  autoload :MediaTypeIdentifier, 'praxis/media_type_identifier'
   autoload :Multipart, 'praxis/types/multipart'
   autoload :Collection, 'praxis/collection'
 
@@ -91,6 +91,12 @@ module Praxis
   require 'praxis/responses/internal_server_error'
   require 'praxis/responses/validation_error'
 
+  module Handlers
+    autoload :JSON, 'praxis/handlers/json'
+    autoload :WWWForm, 'praxis/handlers/www_form'
+    autoload :XML, 'praxis/handlers/xml'
+  end
+
   module BootloaderStages
     autoload :FileLoader, 'praxis/bootloader_stages/file_loader'
     autoload :Environment, 'praxis/bootloader_stages/environment'

data/praxis.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'mime', '~> 0'
   spec.add_dependency 'praxis-mapper', '~> 3.3'
   spec.add_dependency 'praxis-blueprints', '~> 1.3'
-  spec.add_dependency 'attributor', '~> 2.6.0'
+  spec.add_dependency 'attributor', '~> 2.6'
   spec.add_dependency 'thor', '~> 0.18'
   spec.add_dependency 'terminal-table', '~> 1.4'
   spec.add_dependency 'harness', '~> 2'

data/spec/functional_spec.rb

@@ -58,7 +58,8 @@ describe 'Functional specs' do
   end
 
   it 'works' do
-    get '/clouds/1/instances/2?junk=foo&api_version=1.0', nil, 'global_session' => session
+    the_body = StringIO.new("{}") # This is a funny, GET request expecting a body
+    get '/clouds/1/instances/2?junk=foo&api_version=1.0', nil,'rack.input' => the_body,'CONTENT_TYPE' => "application/json", 'global_session' => session
     expect(last_response.status).to eq(200)
     expected = {
       "cloud_id" => 1,
@@ -101,6 +102,7 @@ describe 'Functional specs' do
     let(:body) { form.body.to_s }
 
     it 'works' do
+
       post '/clouds/1/instances?api_version=1.0', body, 'CONTENT_TYPE' => content_type, 'global_session' => session
 
       _reponse_preamble, response = Praxis::MultipartParser.parse(last_response.headers, last_response.body)

data/spec/praxis/application_spec.rb

@@ -1,7 +1,7 @@
 require 'spec_helper'
 
 describe Praxis::Application do
-  describe 'configuration' do
+  context 'configuration' do
     subject(:app) do
       app = Class.new(Praxis::Application).instance
 
@@ -43,4 +43,61 @@ describe Praxis::Application do
       end
     end
   end
+
+  context 'media type handlers' do
+    subject { Class.new(Praxis::Application).instance }
+
+    before do
+      bootloader = double('bootloader')
+      allow(bootloader).to receive(:setup!).and_return(true)
+
+      app = double('built Rack app')
+
+      builder = double('Rack builder')
+      allow(builder).to receive(:run)
+      allow(builder).to receive(:to_app).and_return(app)
+
+      subject.instance_variable_set(:@bootloader, bootloader)
+      subject.instance_variable_set(:@builder, builder)
+    end
+
+    describe '#handler' do
+      let(:new_handler_name) { 'awesomesauce' }
+      let(:new_handler_instance) { double('awesomesauce instance', generate: '', parse: {}) }
+      let(:new_handler_class) { double('awesomesauce', new: new_handler_instance) }
+      let(:bad_handler_instance) { double('bad handler instance', wokka: true, meep: false) }
+      let(:bad_handler_class) { double('bad handler', new: bad_handler_instance) }
+
+      context 'given a Class' do
+        it 'instantiates and registers an instance' do
+          expect(new_handler_class).to receive(:new)
+          subject.handler new_handler_name, new_handler_class
+        end
+      end
+
+      context 'given a non-Class' do
+        it 'raises' do
+          expect {
+            subject.handler('awesomesauce', 'hi') # no instances allowed
+          }.to raise_error(NoMethodError)
+
+          expect {
+            subject.handler('awesomesauce', ::Kernel) # no modules allowed
+          }.to raise_error(NoMethodError)
+        end
+      end
+
+      it 'overrides default handlers' do
+        subject.handler 'json', new_handler_class
+        subject.setup
+        expect(subject.handlers['json']).to eq(new_handler_instance)
+      end
+
+      it 'ensures that handlers will work' do
+        expect {
+          subject.handler new_handler_name, bad_handler_class
+        }.to raise_error(ArgumentError)
+      end
+    end
+  end
 end

data/spec/praxis/handlers/json_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+
+describe Praxis::Handlers::JSON do
+  let(:dictionary) { {"foo" => 1} }
+  let(:dictionary_json) { '{"foo":1}' }
+
+  let(:array) { [1,2,3] }
+  let(:array_json) { '[1,2,3]' }
+
+  describe '#parse' do
+    it 'handles dictionaries' do
+      expect(subject.parse(dictionary_json)).to eq(dictionary)
+    end
+
+    it 'handles arrays' do
+      expect(subject.parse(array_json)).to eq(array)
+
+    end
+  end
+
+  # slightly cheesy: use #parse to test #generate by round-tripping everything
+  describe '#generate' do
+    it 'pretty-prints' do
+      result = subject.generate({"foo" => 1})
+      expect(result).to include("\n")
+      expect(result).to match(/^  /m)
+    end
+
+    it 'handles dictionaries' do
+      expect(subject.parse(subject.generate(dictionary))).to eq(dictionary)
+    end
+
+    it 'handles arrays' do
+      expect(subject.parse(subject.generate(array))).to eq(array)
+    end
+  end
+end

data/spec/praxis/handlers/xml_spec.rb

@@ -0,0 +1,155 @@
+require 'spec_helper'
+
+describe Praxis::Handlers::XML do
+
+  describe '#parse' do
+    after do
+      expect( subject.parse(xml) ).to eq(parsed)
+    end
+
+    #  XML_TYPE_NAMES = {
+    #    "Symbol"     => "symbol",
+    #    "Fixnum"     => "integer",
+    #    "Bignum"     => "integer",
+    #    "BigDecimal" => "decimal",
+    #    "Float"      => "float",
+    #    "TrueClass"  => "boolean",
+    #    "FalseClass" => "boolean",
+    #    "Date"       => "date",
+    #    "DateTime"   => "dateTime",
+    #    "Time"       => "dateTime"
+    #  }
+
+    context "Parsing symbols" do
+      let(:xml){ '<objects type="array"><object type="symbol">a_symbol</object></objects>' }
+      let(:parsed){ [:a_symbol] }
+      it 'works' do end
+    end
+
+    context "Parsing integers" do
+      let(:xml){ '<objects type="array"><object type="integer">1234</object></objects>' }
+      let(:parsed){ [1234] }
+      it 'works' do end
+    end
+
+    context "Parsing decimals" do
+      let(:xml){ '<objects type="array"><object type="decimal">0.1</object></objects>' }
+      let(:parsed){ [0.1] }
+      it 'works' do end
+    end
+
+    context "Parsing floats" do
+      let(:xml){ '<objects type="array"><object type="float">0.1</object></objects>' }
+      let(:parsed){ [0.1] }
+      it 'works' do end
+    end
+
+    context "Parsing booleans" do
+      context "that are true" do
+        let(:xml){ '<objects type="array"><object type="boolean">true</object></objects>' }
+        let(:parsed){ [true] }
+        it 'works' do end
+      end
+      context "that are false" do
+        let(:xml){ '<objects type="array"><object type="boolean">false</object></objects>' }
+        let(:parsed){ [false] }
+        it 'works' do end
+      end
+    end
+
+    context "Parsing dates" do
+      let(:xml){ '<objects type="array"><object type="date">2001-01-01</object></objects>' }
+      let(:parsed){ [Date.parse("2001-01-01")] }
+      it 'works' do end
+    end
+
+    context "Parsing dateTimes" do
+      let(:xml){ '<objects type="array"><object type="dateTime">2015-03-13T19:34:40-07:00</object></objects>' }
+      let(:parsed){ [DateTime.parse("2015-03-13T19:34:40-07:00")] }
+      it 'works' do end
+    end
+
+    context "Parsing hashes" do
+      context "that are empty" do
+        let(:xml){ '<hash></hash>' }
+        let(:parsed){ {} }
+        it 'works' do end
+      end
+      context "with a couple of elements" do
+        let(:xml){ '<hash><one type="integer">1</one><two type="integer">2</two></hash>' }
+        let(:parsed){ {"one"=>1, "two"=>2} }
+        it 'works' do end
+      end
+      context "with a nested hash" do
+        let(:xml){ '<hash><one type="integer">1</one><sub_hash><first>hello</first></sub_hash></hash>' }
+        let(:parsed){ {"one"=>1, "sub_hash"=>{"first"=>"hello"} } }
+        it 'works' do end
+      end
+      context "with a nested array" do
+        let(:xml){ '<hash><one type="integer">1</one><two type="array"><object>just text</object></two></hash>' }
+        let(:parsed){ {"one"=>1, "two" => ["just text"] } }
+        it 'works' do end
+      end
+
+    end
+
+    context "Parsing an Array" do
+      context 'with a couple of simple elements in it' do
+        let(:xml){ '<objects type="array"><object>just text</object><object type="integer">1</object></objects>' }
+        let(:parsed){ ["just text", 1] }
+        it 'works' do end
+      end
+      context "with a nested hash" do
+        let(:xml){ '<objects type="array"><object>just text</object><object><one type="integer">1</one></object></objects>' }
+        let(:parsed){ ["just text", { "one" => 1}] }
+        it 'works' do end
+      end
+    end
+
+    context "Parsing XML strings created with .to_xml" do
+      let(:xml){ parsed.to_xml }
+      context 'array with a couple of simple elements in it' do
+        let(:parsed){ ["just text", 1] }
+        it 'works' do end
+      end
+      context 'a hash with a couple of simple elements in it' do
+        let(:parsed){ { "one"=>"just text", "two"=> 1 } }
+        it 'works' do end
+      end
+      context 'a array with elements of all types' do
+        let(:parsed){ ["just text",:a,1,BigDecimal.new(100),0.1,true,Date.new] }
+        it 'works' do end
+      end
+      context 'a hash with a complex substructure' do
+        let(:parsed) do
+          Hash(
+              "text" => "just text",
+              "symbol" => :a,
+              "num" => 1,
+              "BD" => BigDecimal.new(100),
+              "float" => 0.1,
+              "truthyness" => true,
+              "day" => Date.new )
+        end
+        it 'works' do end
+      end
+
+      context "transformed characters when using .to_xml" do
+        context 'underscores become dashes' do
+          let(:xml){ {"one_thing"=>1, "two_things"=>2}.to_xml  }
+          let(:parsed){ {"one-thing"=>1, "two-things"=>2} }
+          it 'works' do end
+        end
+        context 'spaces become dashes' do
+          let(:xml){ {"one thing"=>1, "two things"=>2}.to_xml  }
+          let(:parsed){ {"one-thing"=>1, "two-things"=>2} }
+          it 'works' do end
+        end
+      end
+    end
+
+    describe '#generate' do
+      it 'has tests'
+    end
+  end
+end