praxis 0.16.1 → 0.17.0

data/lib/praxis/response_definition.rb

@@ -55,6 +55,15 @@ 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) )
@@ -120,6 +129,14 @@ module Praxis
           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)
@@ -137,12 +154,16 @@ module Praxis
       { :value => data_value, :type => data_type }
     end
 
-    def validate( response )
+    def validate(response, validate_body: false)
       validate_status!(response)
       validate_location!(response)
       validate_headers!(response)
       validate_content_type!(response)
       validate_parts!(response)
+
+      if validate_body
+        validate_body!(response)
+      end
     end
 
     def parts(proc=nil, like: nil,  **args, &block)
@@ -227,7 +248,7 @@ module Praxis
 
     # Validates Content-Type header and response media type
     #
-    # @param [Object] action
+    # @param [Object] response
     #
     # @raise [Exceptions::Validation] When there is a missing required header
     #
@@ -245,13 +266,38 @@ module Praxis
       end
     end
 
+    # Validates response body
+    #
+    # @param [Object] response
+    #
+    # @raise [Exceptions::Validation]  When there is a missing required header..
+    def validate_body!(response)
+      return unless media_type
+      return if media_type.kind_of? SimpleMediaType
+
+      errors = self.media_type.validate(self.media_type.load(response.body))
+      if errors.any?
+        message = "Invalid response body for #{media_type.identifier}." +
+          "Errors: #{errors.inspect}"
+          raise Exceptions::Validation.new(message, errors: errors)
+      end
+
+    end
+
     def validate_parts!(response)
       return unless parts
 
-      response.parts.each do |name, part|
-        parts.validate(part)
+      case response.body
+      when Praxis::Types::MultipartArray
+        response.body.each do |part|
+          parts.validate(part)
+        end
+      else
+        # TODO: remove with other Multipart deprecations.
+        response.parts.each do |name, part|
+          parts.validate(part)
+        end
       end
-
     end
 
   end

data/lib/praxis/responses/http.rb

@@ -18,6 +18,11 @@ module Praxis
     # being created.
     class Created < Praxis::Response
       self.status = 201
+
+      def initialize(status:self.class.status, headers:{}, body:'', location: nil)
+        super(status: status, headers: headers, body: body)
+        headers['Location'] = location if location
+      end
     end
 
 

data/lib/praxis/responses/multipart_ok.rb

@@ -0,0 +1,51 @@
+module Praxis
+  module Responses
+    class MultipartOk < Ok
+
+      def initialize(status:self.class.status, headers:{}, body:'')
+        @name    = response_name
+        @status  = status
+        @headers = headers
+        @body    = body
+      end
+
+      def handle
+        case @body
+        when Praxis::Types::MultipartArray
+          if @headers['Content-Type'].nil?
+            @headers['Content-Type'] = @body.content_type
+          end
+        end
+      end
+
+
+      def encode!
+        case @body
+        when Praxis::Types::MultipartArray
+          @body = @body.dump
+        else
+          super
+        end
+      end
+
+      def finish
+        format!
+        encode!
+
+        @body = Array(@body)
+
+        [@status, @headers, @body]
+      end
+
+    end
+
+  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

@@ -3,20 +3,20 @@ module Praxis
   module Responses
 
     class ValidationError < BadRequest
-      def initialize(errors: nil, exception: nil, message: nil, **opts)
+      def initialize(summary:, errors: nil, exception: nil, **opts)
         super(**opts)
         @headers['Content-Type'] = 'application/json' #TODO: might want an error mediatype
         @errors = errors
+        unless @errors # The exception message will the the only error if no errors are passed in
+           @errors = [exception.message] if exception && exception.message
+         end
         @exception = exception
-        @message = message || (exception && exception.message)
+        @summary = summary
       end
 
       def format!
-        if @errors
-          @body = {name: 'ValidationError', errors: @errors}
-        elsif @message
-          @body = {name: 'ValidationError', message: @message}
-        end
+        @body = {name: 'ValidationError', summary: @summary }
+        @body[:errors] = @errors if @errors
 
         if @exception && @exception.cause
           @body[:cause] = {name: @exception.cause.class.name, message: @exception.cause.message}

data/lib/praxis/restful_doc_generator.rb

@@ -108,6 +108,10 @@ module Praxis
         end
       end
 
+      def parent
+        @controller_config.parent
+      end
+
       def friendly_name
         # FIXME: is it really about the controller? or the attached resource definition?
         segments = self.name.split("::")
@@ -160,7 +164,7 @@ module Praxis
     def dump_example_for(context_name, object)
       example = object.example(Array(context_name))
       if object.is_a? Praxis::Blueprint
-        example.render(:master)
+        example.render(view: :master)
       elsif object.is_a? Attributor::Attribute
         object.dump(example)
       else
@@ -216,7 +220,7 @@ module Praxis
             type_output[:views].each do |view_name, view_info|
               # Add and example for each view
               unless( type < Praxis::Links ) #TODO: why do we need to skip an example for links?
-                view_info[:example] = example_data.render(view_name)
+                view_info[:example] = example_data.render(view: view_name)
               end
             end
           end
@@ -224,7 +228,7 @@ module Praxis
           # ...but not for links or link classes (there's no object container context if done alone!!)
           unless( type < Praxis::Links ) #TODO: again, why is this special?
             type_output[:example] = if example_data.respond_to? :render
-              example_data.render(:master)
+              example_data.render(view: :master)
             else
               type.dump(example_data)
             end
@@ -259,6 +263,7 @@ module Praxis
       @resources.each do |r|
         index[r.version] ||= Hash.new
         info = {controller: r.id, name: r.name}
+        info[:parent] = r.parent.controller ? r.parent.controller.id : r.parent.id if r.parent
         if r.media_type
           info[:media_type] = r.media_type.id
           media_types_seen_from_controllers << r.media_type
@@ -275,7 +280,7 @@ module Praxis
 
         reportable_types.each do |type|
           index[version] ||= Hash.new
-          display_name = type.name.split("::").last + " (*)" #somehow this is just a MT so we probably wanna mark it different
+          display_name = type.name.split("::").last
           if index[version].has_key? display_name
             raise "Display name already taken for version #{version}! #{display_name}"
           end

data/lib/praxis/route.rb

@@ -1,14 +1,15 @@
 module Praxis
 
   class Route
-    attr_accessor :verb, :path, :version, :name, :options
+    attr_accessor :verb, :path, :version, :name, :prefixed_path, :options
 
-    def initialize(verb, path, version='n/a', name:nil, **options)
+    def initialize(verb, path, version='n/a', name:nil, prefixed_path:nil, **options)
       @verb = verb
       @path = path
       @version = version
       @name = name
       @options = options
+      @prefixed_path = prefixed_path
     end
 
     def describe

data/lib/praxis/router.rb

@@ -1,9 +1,11 @@
-require 'mustermann/router/rack'
+require 'praxis/router/rack'
 
 module Praxis
 
   class Router
-    attr_reader :request_class, :application
+    attr_reader :request_class
+    attr_reader :application
+
 
     class VersionMatcher
       def initialize(target, version: 'n/a')
@@ -11,7 +13,7 @@ module Praxis
         @version = version
       end
       def call(request)
-        if request.version(@target.action.resource_definition.version_options) == @version
+        if request.version == @version
           @target.call(request)
         else
           # Version doesn't match, pass and continue
@@ -41,15 +43,23 @@ module Praxis
 
     def initialize(application, request_class: Praxis::Request)
       @routes = Hash.new do |hash, verb|
-          hash[verb] = RequestRouter.new
+        hash[verb] = RequestRouter.new
       end
       @request_class = request_class
       @application = application
     end
 
     def add_route(target, route)
-      version_wrapper = VersionMatcher.new(target, version: route.version)
-      @routes[route.verb].on(route.path, call: version_wrapper)
+      path_versioning = (Application.instance.versioning_scheme == :path)
+
+      # DEPRECATED: remove with ResourceDefinition.version using: :path
+      path_versioning ||= (target.action.resource_definition.version_options[:using] == :path)
+
+      unless path_versioning
+        target = VersionMatcher.new(target, version: route.version)
+      end
+
+      @routes[route.verb].on(route.path, call: target)
     end
 
     def call(env_or_request)
@@ -67,26 +77,26 @@ module Praxis
       result = r.call(request) if r
       # If we didn't have an exact verb route, or if we did but the rest or route conditions didn't match
       if( r == nil || result == :not_found )
-         # Fallback to a wildcard router, if there is one registered
+        # Fallback to a wildcard router, if there is one registered
         result = if @routes.key?('ANY')
-           @routes['ANY'].call(request)
-         else
-           :not_found
-         end
+          @routes['ANY'].call(request)
+        else
+          :not_found
+        end
       end
 
       if result == :not_found
         # no need to try :path as we cannot really know if you've attempted to pass a version through it here
         # plus we wouldn't have tracked it as unmatched
-        version = request.version(using: [:header,:params])
+        version = request.version
         attempted_versions = request.unmatched_versions
         body = "NotFound"
         unless attempted_versions.empty? || (attempted_versions.size == 1 && attempted_versions.first == 'n/a')
           body += if version == 'n/a'
-                    ". Your request did not specify an API version.".freeze
-                  else
-                    ". Your request speficied API version = \"#{version}\"."
-                  end
+            ". Your request did not specify an API version.".freeze
+          else
+            ". Your request speficied API version = \"#{version}\"."
+          end
           pretty_versions = attempted_versions.collect(&:inspect).join(', ')
           body += " Available versions = #{pretty_versions}."
         end

data/lib/praxis/router/rack.rb

@@ -0,0 +1,51 @@
+# Originally from:
+# https://github.com/rkh/mustermann/blob/500a603fffe0594ab842d72addcc449eedd6d5be/mustermann/lib/mustermann/router/rack.rb
+# Copied here after its removal from Mustermann proper
+
+require 'praxis/router/simple'
+
+module Mustermann
+  module Router
+    # Simple pattern based router that allows matching paths to a given Rack application.
+    #
+    # @example config.ru
+    #    router = Mustermann::Rack.new do
+    #      on '/' do |env|
+    #        [200, {'Content-Type' => 'text/plain'}, ['Hello World!']]
+    #      end
+    #
+    #      on '/:name' do |env|
+    #        name = env['mustermann.params']['name']
+    #        [200, {'Content-Type' => 'text/plain'}, ["Hello #{name}!"]]
+    #      end
+    #
+    #      on '/something/*', call: SomeApp
+    #    end
+    #
+    #    # in a config.ru
+    #    run router
+    class Rack < Simple
+      def initialize(env_prefix: "mustermann", params_key: "#{env_prefix}.params", pattern_key: "#{env_prefix}.pattern", **options, &block)
+        @params_key, @pattern_key = params_key, pattern_key
+        options[:default] = [404, {"Content-Type" => "text/plain", "X-Cascade" => "pass"}, ["Not Found"]] unless options.include? :default
+        super(**options, &block)
+      end
+
+      def invoke(callback, env, params, pattern)
+        params_was, pattern_was             = env[@params_key], env[@pattern_key]
+        env[@params_key], env[@pattern_key] = params, pattern
+        response = callback.call(env)
+        response[1].each { |k,v| throw :pass if k.downcase == 'x-cascade' and v == 'pass' }
+        response
+      ensure
+        env[@params_key], env[@pattern_key] = params_was, pattern_was
+      end
+
+      def string_for(env)
+        env['PATH_INFO']
+      end
+
+      private :invoke, :string_for
+    end
+  end
+end

data/lib/praxis/router/simple.rb

@@ -0,0 +1,146 @@
+# Originally from:
+# https://github.com/rkh/mustermann/blob/500a603fffe0594ab842d72addcc449eedd6d5be/mustermann/lib/mustermann/router/simple.rb
+# Copied here after its removal from Mustermann proper
+
+require 'mustermann'
+
+module Mustermann
+  module Router
+    # Simple pattern based router that allows matching a string to a given callback.
+    #
+    # @example
+    #   require 'mustermann/router/simple'
+    #
+    #   router = Mustermann::Router::Simple.new do
+    #     on ':name/:sub' do |string, params|
+    #       params['sub']
+    #     end
+    #
+    #     on 'foo' do
+    #       "bar"
+    #     end
+    #   end
+    #
+    #   router.call("foo") # => "bar"
+    #   router.call("a/b") # => "b"
+    #   router.call("bar") # => nil
+    class Simple
+      # Default value for when no pattern matches
+      attr_accessor :default
+
+      # @example with a default value
+      #   require 'mustermann/router/simple'
+      #
+      #   router = Mustermann::Router::Simple.new(default: 42)
+      #   router.on(':name', capture: :digit) { |string| string.to_i }
+      #   router.call("23")      # => 23
+      #   router.call("example") # => 42
+      #
+      # @example block with implicit receiver
+      #   require 'mustermann/router/simple'
+      #
+      #   router = Mustermann::Router::Simple.new do
+      #     on('/foo') { 'foo' }
+      #     on('/bar') { 'bar' }
+      #   end
+      #
+      # @example block with explicit receiver
+      #   require 'mustermann/router/simple'
+      #
+      #   router = Mustermann::Router::Simple.new(type: :rails) do |r|
+      #     r.on('/foo') { 'foo' }
+      #     r.on('/bar') { 'bar' }
+      #   end
+      #
+      # @param default value to be returned if nothing matches
+      # @param options [Hash] pattern options
+      # @return [Mustermann::Router::Simple] new router instance
+      def initialize(default: nil, **options, &block)
+        @options = options
+        @map     = []
+        @default = default
+
+        block.arity == 0 ? instance_eval(&block) : yield(self) if block
+      end
+
+      # @example
+      #   require 'mustermann/router/simple'
+      #
+      #   router = Mustermann::Router::Simple.new
+      #   router.on(':a/:b') { 42 }
+      #   router['foo/bar'] # => <#Proc:...>
+      #   router['foo_bar'] # => nil
+      #
+      # @return [#call, nil] callback for given string, if a pattern matches
+      def [](string)
+        string = string_for(string) unless string.is_a? String
+        @map.detect { |p,v| p === string }[1]
+      end
+
+      # @example
+      #   require 'mustermann/router/simple'
+      #
+      #   router = Mustermann::Router::Simple.new
+      #   router['/:name'] = proc { |string, params| params['name'] }
+      #   router.call('/foo') # => "foo"
+      #
+      # @param pattern [String, Mustermann::Pattern] matcher
+      # @param callback [#call] callback to call on match
+      # @see #on
+      def []=(pattern, callback)
+        on(pattern, call: callback)
+      end
+
+      # @example with block
+      #   require 'mustermann/router/simple'
+      #
+      #   router = Mustermann::Router::Simple.new
+      #
+      #   router.on(':a/:b') { 42 }
+      #   router.call('foo/bar') # => 42
+      #   router.call('foo_bar') # => nil
+      #
+      # @example with callback option
+      #   require 'mustermann/router/simple'
+      #
+      #   callback = proc { 42 }
+      #   router   = Mustermann::Router::Simple.new
+      #
+      #   router.on(':a/:b', call: callback)
+      #   router.call('foo/bar') # => 42
+      #   router.call('foo_bar') # => nil
+      #
+      # @param patterns [Array<String, Pattern>]
+      # @param call [#call] callback object, need to hand in block if missing
+      # @param options [Hash] pattern options
+      def on(*patterns, call: Proc.new, **options)
+        patterns.each do |pattern|
+          pattern = Mustermann.new(pattern.to_str, **options, **@options) if pattern.respond_to? :to_str
+          @map << [pattern, call]
+        end
+      end
+
+      # Finds the matching callback and calls `call` on it with the given input and the params.
+      # @return the callback's return value
+      def call(input)
+        @map.each do |pattern, callback|
+          catch(:pass) do
+            next unless params = pattern.params(string_for(input))
+            return invoke(callback, input, params, pattern)
+          end
+        end
+        @default
+      end
+
+      def invoke(callback, input, params, pattern)
+        callback.call(input, params)
+      end
+
+      def string_for(input)
+        input.to_str
+      end
+
+      private :invoke, :string_for
+    end
+  end
+end