praxis 0.16.1 → 0.17.0

data/lib/praxis/api_general_info.rb

@@ -1,9 +1,17 @@
 module Praxis
   class ApiGeneralInfo
 
-    def initialize(global_info=nil)
-      @global_info = global_info
+    attr_reader :version
+
+    def initialize(global_info=nil, version: nil)
       @data = Hash.new
+      @global_info = global_info
+      @version = version
+
+      if @global_info.nil? # this *is* the global info
+        version_with [:header, :params]
+      end
+
     end
 
     def get(k)
@@ -40,14 +48,49 @@ module Praxis
       end
     end
 
+    def version_with(val=nil)
+      if val.nil?
+        get(:version_with)
+      else
+        if @global_info.nil? # this *is* the global info
+          Application.instance.versioning_scheme = val
+          set(:version_with, val)
+        else
+          raise "Use of version_with is only allowed in the global part of " \
+            "the API definition (but you are attempting to use it in the API " \
+            "definition of version #{self.version}"
+        end
+      end
+    end
+
+    def endpoint(val=nil)
+      if val.nil?
+        get(:endpoint)
+      else
+        if @global_info.nil? # this *is* the global info
+          set(:endpoint, val)
+        else
+          raise "Use of endpoint is only allowed in the global part of " \
+            "the API definition (but you are attempting to use it in the API " \
+            "definition of version #{self.version}"
+        end
+      end
+    end
+
+
     def base_path(val=nil)
       if val
         return set(:base_path, val)
       end
 
-      if @global_info
+      if @global_info # this is for a specific version
+        global_path = @global_info.base_path
+        if version_with == :path
+          global_pattern = Mustermann.new(global_path)
+          global_path = global_pattern.expand(Request::API_VERSION_PARAM_NAME => self.version)
+        end
+
         version_path = @data.fetch(:base_path,'')
-        global_path = @global_info.get(:base_path)
         "#{global_path}#{version_path}"
       else
         @data.fetch(:base_path,'')
@@ -62,9 +105,10 @@ module Praxis
       end
     end
 
+
     def describe
       hash = { schema_version: "1.0".freeze }
-      [:name, :title, :description, :base_path].each do |attr|
+      [:name, :title, :description, :base_path, :version_with, :endpoint].each do |attr|
         val = self.__send__(attr)
         hash[attr] = val unless val.nil?
       end

data/lib/praxis/application.rb

@@ -20,6 +20,9 @@ module Praxis
     attr_accessor :handlers
     attr_accessor :root
     attr_accessor :error_handler
+    attr_accessor :validation_handler
+
+    attr_accessor :versioning_scheme
 
 
     def self.configure
@@ -31,6 +34,7 @@ module Praxis
       @resource_definitions = Set.new
 
       @error_handler = ErrorHandler.new
+      @validation_handler = ValidationHandler.new
 
       @router = Router.new(self)
 
@@ -46,13 +50,17 @@ module Praxis
       @root = nil
       @logger = Logger.new(STDOUT)
     end
-    
+
+
     def setup(root: '.')
+      return self unless @app.nil?
+
       @root = Pathname.new(root).expand_path
 
       builtin_handlers = {
-          'json'                  => Praxis::Handlers::JSON,
-          'x-www-form-urlencoded' => Praxis::Handlers::WWWForm
+        'plain' => Praxis::Handlers::Plain,
+        'json' => Praxis::Handlers::JSON,
+        'x-www-form-urlencoded' => Praxis::Handlers::WWWForm
       }
       # Register built-in handlers unless the app already provided its own
       builtin_handlers.each_pair do |name, handler|
@@ -120,6 +128,6 @@ module Praxis
     def config=(config)
       @config.set(config)
     end
-    
+
   end
 end

data/lib/praxis/bootloader.rb

@@ -49,6 +49,7 @@ module Praxis
       after(:app) do
         Praxis::Mapper.finalize!
         Praxis::Blueprint.finalize!
+        Praxis::ResourceDefinition.finalize!
       end
 
     end

data/lib/praxis/bootloader_stages/environment.rb

@@ -42,6 +42,8 @@ module Praxis
         application.config do
           attribute :praxis do
             attribute :validate_responses, Attributor::Boolean, default: false
+            attribute :validate_response_bodies, Attributor::Boolean, default: false
+
             attribute :show_exceptions, Attributor::Boolean, default: false
             attribute :x_cascade, Attributor::Boolean, default: true
           end

data/lib/praxis/bootloader_stages/routing.rb

@@ -14,7 +14,7 @@ module Praxis
         
         def call(request)
           request.action = @action
-          dispatcher = Dispatcher.current( application: @application)
+          dispatcher = Dispatcher.current(application: @application)
 
           dispatcher.dispatch(@controller, @action, request)
         end

data/lib/praxis/bootloader_stages/subgroup_loader.rb

@@ -20,6 +20,7 @@ module Praxis
         order.each do |group|
           @stages << FileLoader.new(group, application, path: [name, group])
         end
+        setup_deferred_callbacks!
       end
     end
 

data/lib/praxis/exceptions/validation.rb

@@ -1,6 +1,13 @@
 module Praxis
   module Exceptions
     class Validation < Exception
+
+      attr_accessor :errors
+      def initialize(message, errors: nil)
+        super(message)
+        @errors = errors
+      end
+
     end
   end
 end

data/lib/praxis/handlers/plain.rb

@@ -0,0 +1,16 @@
+module Praxis
+  module Handlers
+    class Plain
+      # no-op
+      def parse(entity)
+        entity
+      end
+
+      # no-op
+      def generate(structured_data)
+        structured_data
+      end
+
+    end
+  end
+end

data/lib/praxis/handlers/xml.rb

@@ -11,7 +11,7 @@ module Praxis
         ActiveSupport::XmlMini.backend = 'Nokogiri'
       rescue LoadError
         raise Praxis::Exceptions::InvalidConfiguration,
-              "XML handler depends on builder ~> 3.2 and nokogiri ~> 1.6; please add them to your Gemfile"
+          "XML handler depends on builder ~> 3.2 and nokogiri ~> 1.6; please add them to your Gemfile"
       end
 
       # Parse an XML document into structured data.
@@ -40,14 +40,14 @@ module Praxis
 
         case type
         when nil
-          if node.children.size == 1 && node.child.text?
+          if (node.children.size == 1 && node.child.text?) || node.children.size == 0
             # leaf text node
             return node.content
           else
             # A hash
             return node.children.each_with_object({}) do |child, hash|
               next unless child.element? # There might be text fragments like newlines...spaces
-              hash[child.name] = process(child, child.attributes['type'])
+              hash[child.name.underscore] = process(child, child.attributes['type'])
             end
           end
         when "array"
@@ -75,4 +75,4 @@ module Praxis
       end
     end
   end
-end
+end

data/lib/praxis/links.rb

@@ -49,14 +49,16 @@ module Praxis
       self
     end
 
-    def self.describe(shallow=false)
-      super(false) # Links must always describe attributes
+    def self.describe(shallow=false,**opts)
+      super(false,**opts) # Links must always describe attributes
     end
-    
+
     def self._finalize!
       super
       if @attribute
+        # Master and default views must be set for all attributes, always using their :link view
         self.define_default_view
+        self.define_master_view
         self.fixup_reference_struct_methods
       end
     end
@@ -95,6 +97,14 @@ module Praxis
       end
     end
 
+    def self.define_master_view
+
+      view(:master) {}
+      self.attributes.each do |name, attribute|
+        view(:master).attribute(name, view: :link)
+      end
+    end
+
     # Define methods on the inner Struct class for
     # links that do not have corresponding top-level attributes.
     # This is primarily necessary only for example generation.

data/lib/praxis/media_type_identifier.rb

@@ -130,6 +130,9 @@ module Praxis
       s
     end
 
+    alias_method :to_str, :to_s
+
+
     # If parameters are empty, return self; otherwise return a new object consisting of this type
     # minus parameters.
     #

data/lib/praxis/multipart/parser.rb

@@ -4,18 +4,23 @@ require 'rack/utils'
 
 module Praxis
   class MultipartParser
-    EOL = "\r\n"
-    MULTIPART_BOUNDARY = "AaB03x"
-    MULTIPART = %r|\Amultipart/.*boundary=\"?([^\";,]+)\"?|n
-    TOKEN = /[^\s()<>,;:\\"\/\[\]?=]+/
-    CONDISP = /Content-Disposition:\s*#{TOKEN}\s*/i
-    DISPPARM = /;\s*(#{TOKEN})=("(?:\\"|[^"])*"|#{TOKEN})/
-    RFC2183 = /^#{CONDISP}(#{DISPPARM})+$/i
-    BROKEN_QUOTED = /^#{CONDISP}.*;\sfilename="(.*?)"(?:\s*$|\s*;\s*#{TOKEN}=)/i
-    BROKEN_UNQUOTED = /^#{CONDISP}.*;\sfilename=(#{TOKEN})/i
-    MULTIPART_CONTENT_TYPE = /Content-Type: (.*)#{EOL}/ni
-    MULTIPART_CONTENT_DISPOSITION = /Content-Disposition:.*\s+name="?([^\";]*)"?/ni
-    MULTIPART_CONTENT_ID = /Content-ID:\s*([^#{EOL}]*)/ni
+    EOL = "\r\n".freeze
+    MULTIPART_BOUNDARY = "AaB03x".freeze
+    MULTIPART = %r|\Amultipart/.*boundary=\"?([^\";,]+)\"?|n.freeze
+    TOKEN = /[^\s()<>,;:\\"\/\[\]?=]+/.freeze
+    CONDISP = /Content-Disposition:\s*#{TOKEN}\s*/i.freeze
+    DISPPARM = /;\s*(#{TOKEN})=("(?:\\"|[^"])*"|#{TOKEN})/.freeze
+    RFC2183 = /^#{CONDISP}(#{DISPPARM})+$/i.freeze
+    BROKEN_QUOTED = /^#{CONDISP}.*;\sfilename="(.*?)"(?:\s*$|\s*;\s*#{TOKEN}=)/i.freeze
+    BROKEN_UNQUOTED = /^#{CONDISP}.*;\sfilename=(#{TOKEN})/i.freeze
+    MULTIPART_CONTENT_TYPE = /Content-Type: (.*)#{EOL}/ni.freeze
+    MULTIPART_CONTENT_DISPOSITION = /Content-Disposition:.*\s+name="?([^\";]*)"?/ni.freeze
+    MULTIPART_CONTENT_ID = /Content-ID:\s*([^#{EOL}]*)/ni.freeze
+
+    HEADER_KV = /(?<k>[^:]+): (?<v>.*)/.freeze
+    UNTIL_NEWLINE = /\A([^\n]*\n)/.freeze
+    TERMINAL_CRLF = /\r\n$/.freeze
+
 
     BUFSIZE = 16384
 
@@ -30,7 +35,7 @@ module Praxis
         @io << chunk
       end
       @io.rewind
-      @parts = Hash.new
+      @parts = Array.new
     end
 
     def parse
@@ -53,13 +58,15 @@ module Praxis
         filename, data = get_data(filename, body, content_type, name, head)
 
         parsed_headers = head.split(EOL).each_with_object(Hash.new) do |line, hash|
-          match = /(?<k>[^:]+): (?<v>.*)/.match(line)
+          match = HEADER_KV.match(line)
           k = match[:k]
           v = match[:v]
           hash[k] = v
         end
 
-        @parts[name] = MultipartPart.new(data, parsed_headers, filename: filename)
+        part = MultipartPart.new(data, parsed_headers, name: name, filename: filename)
+
+        @parts << part
 
         # break if we're at the end of a buffer, but not if it is the end of a field
         break if (@buf.empty? && $1 != EOL) || @content_length == -1
@@ -72,17 +79,16 @@ module Praxis
 
     private
     def setup_parse
-      return false unless @headers['Content-Type'] =~ MULTIPART
+      unless (match = MULTIPART.match @headers['Content-Type'])
+        return false
+      end
 
-      @boundary = "--#{$1}"
+      @boundary = "--#{match[1]}"
 
       @buf = ""
 
       @params = Rack::Utils::KeySpaceConstrainedParams.new
 
-      #@io = @env['rack.input']
-      #@io.rewind
-
       @boundary_size = Rack::Utils.bytesize(@boundary) + EOL.size
 
       if @content_length = @headers['Content-Length']
@@ -107,10 +113,10 @@ module Praxis
         raise EOFError, "bad content body" unless content
         @buf << content
 
-        while @buf.gsub!(/\A([^\n]*\n)/, '')
+        while @buf.gsub!(UNTIL_NEWLINE, '')
           read_buffer = $1
           if read_buffer == full_boundary
-            return preamble.gsub!(/\r\n$/,'')
+            return preamble.gsub!(TERMINAL_CRLF,'')
           else
             preamble << read_buffer
           end
@@ -140,7 +146,7 @@ module Praxis
 
           if filename
             body = Tempfile.new("RackMultipart")
-            body.binmode  if body.respond_to?(:binmode)
+            body.binmode if body.respond_to?(:binmode)
           end
 
           next
@@ -182,32 +188,19 @@ module Praxis
     end
 
     def get_data(filename, body, content_type, name, head)
-      data = nil
-      if filename == ""
-        # filename is blank which means no file has been selected
-        return data
-      elsif filename
-        body.rewind
-        
-        # Take the basename of the upload's original filename.
-        # This handles the full Windows paths given by Internet Explorer
-        # (and perhaps other broken user agents) without affecting
-        # those which give the lone filename.
-        filename = filename.split(/[\/\\]/).last
-
-        data = {:filename => filename, :type => content_type,
-                :name => name, :tempfile => body, :head => head}
-      elsif !filename && content_type && body.is_a?(IO)
-        body.rewind
-
-        # Generic multipart cases, not coming from a form
-        data = {:type => content_type,
-                :name => name, :tempfile => body, :head => head}
-      else
-        data = body
-      end
+      # filename is blank which means no file has been selected
+      return nil if filename == ""
+
+      # Take the basename of the upload's original filename.
+      # This handles the full Windows paths given by Internet Explorer
+      # (and perhaps other broken user agents) without affecting
+      # those which give the lone filename.
+      filename = filename.split(/[\/\\]/).last if filename
+
+      # Rewind any IO bodies so the app can read them at its leisure
+      body.rewind if  body.is_a?(IO)
 
-      [filename, data]
+      [filename, body]
     end
   end
 end

data/lib/praxis/multipart/part.rb

@@ -1,21 +1,140 @@
 module Praxis
   class MultipartPart
+    include Attributor::Type
 
     attr_accessor :body
     attr_accessor :headers
     attr_accessor :filename
-    
-    def initialize(body, headers={}, filename: nil)
+    attr_accessor :name
+    attr_accessor :payload_attribute
+    attr_accessor :headers_attribute
+    attr_accessor :filename_attribute
+
+    def self.check_option!(name, definition)
+      case name
+      when :payload_attribute, :headers_attribute, :filename_attribute
+        unless definition.nil? || definition.kind_of?(Attributor::Attribute)
+          raise Attributor::AttributorException.new("Value for option #{name.inspect} must be an Attribute. Got #{definition.class.name}")
+        end
+      else
+        return :unknown
+      end
+
+      :ok
+    end
+
+    def self.native_type
+      self
+    end
+
+    def self.example(context=nil, options:{})
+      if (payload_attribute = options[:payload_attribute])
+        payload = payload_attribute.example(context + ['payload'])
+      end
+
+      headers = if (headers_attribute = options[:headers_attribute])
+        headers_attribute.example(context + ['headers'])
+      else
+        {}
+      end
+
+      name = options[:name]
+
+      filename = if (filename_attribute = options[:filename_attribute])
+        filename_attribute.example(context + ['filename'])
+      else
+        nil
+      end
+
+      self.new(payload, headers, name: name, filename: filename,
+               payload_attribute: payload_attribute,
+               headers_attribute: headers_attribute,
+               filename_attribute: filename_attribute)
+    end
+
+
+    def self.describe(shallow=true, example: nil, options:{})
+      hash = super(shallow, example: example)
+
+      if (payload_attribute = options[:payload_attribute])
+        payload_example = example.payload if example
+        hash[:payload] = payload_attribute.describe(shallow, example: payload_example)
+      end
+      if (headers_attribute = options[:headers_attribute])
+        headers_example = example.headers if example
+        hash[:headers] = headers_attribute.describe(shallow, example: headers_example)
+      end
+      if (filename_attribute = options[:filename_attribute])
+        filename_example = example.filename if example
+        hash[:filename] = filename_attribute.describe(shallow, example: filename_example)
+      end
+
+      hash
+    end
+
+    def initialize(body, headers={}, name: nil, filename: nil, payload_attribute: nil, headers_attribute: nil, filename_attribute: nil)
+      @name = name
       @body = body
       @headers = headers
+
+      if content_type.nil?
+        self.content_type = 'text/plain'
+      end
+
       @filename = filename
+
+      @payload_attribute = payload_attribute
+      @headers_attribute = headers_attribute
+      @filename_attribute = filename_attribute
+
+      reset_content_disposition
+    end
+
+    alias_method :payload, :body
+    alias_method :payload=, :body=
+
+    def attribute=(attribute)
+      unless self.kind_of?(attribute.type)
+        raise ArgumentError, "invalid attribute type #{attribute.type}"
+      end
+
+      if attribute.options.key? :payload_attribute
+        @payload_attribute = attribute.options[:payload_attribute]
+      end
+
+      if attribute.options.key? :headers_attribute
+        @headers_attribute = attribute.options[:headers_attribute]
+      end
+
+      if attribute.options.key? :filename_attribute
+        @filename_attribute = attribute.options[:filename_attribute]
+      end
+
+    end
+
+    def load_payload(context=Attributor::DEFAULT_ROOT_CONTEXT)
+      if self.payload_attribute
+        value = if self.payload.kind_of?(String)
+          handler.parse(self.payload)
+        else
+          self.payload
+        end
+
+        self.payload = self.payload_attribute.load(value)
+      end
+    end
+
+    def load_headers(context=Attributor::DEFAULT_ROOT_CONTEXT)
+      if self.headers_attribute
+        self.headers = self.headers_attribute.load(self.headers)
+      end
     end
 
     # Determine the content type of this response.
     #
     # @return [MediaTypeIdentifier]
     def content_type
-      MediaTypeIdentifier.load(headers['Content-Type']).freeze
+      @content_type ||= MediaTypeIdentifier.load(headers['Content-Type']).freeze
     end
 
     # Set the content type for this response.
@@ -24,6 +143,7 @@ module Praxis
     # @return [String]
     # @param [String,MediaTypeIdentifier] identifier
     def content_type=(identifier)
+      @content_type = nil
       headers['Content-Type'] = MediaTypeIdentifier.load(identifier).to_s
     end
 
@@ -34,9 +154,82 @@ module Praxis
     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.
         @body = JSON.pretty_generate(@body)
       end
     end
 
+    def validate_headers(context=Attributor::DEFAULT_ROOT_CONTEXT)
+      return [] unless self.headers_attribute
+
+      self.headers_attribute.validate(headers, context + ['headers'])
+    end
+
+    def validate_payload(context=Attributor::DEFAULT_ROOT_CONTEXT)
+      return [] unless self.payload_attribute
+
+      self.payload_attribute.validate(payload, context + ['payload'])
+    end
+
+    def validate_filename(context=Attributor::DEFAULT_ROOT_CONTEXT)
+      return [] unless self.filename_attribute
+
+      self.filename_attribute.validate(filename, context + ['filename'])
+    end
+
+    def validate(context=Attributor::DEFAULT_ROOT_CONTEXT)
+      errors = validate_headers(context)
+      errors.push *validate_payload(context)
+      errors.push *validate_filename(context)
+    end
+
+    def reset_content_disposition
+      self.headers['Content-Disposition'] = begin
+        disposition = "form-data; name=#{name}"
+        if filename
+          disposition += "; filename=#{filename}"
+        end
+
+        disposition
+      end
+    end
+
+
+    def name=(name)
+      @name = name
+      reset_content_disposition
+      name
+    end
+
+    def filename=(filename)
+      @filename = filename
+      reset_content_disposition
+      filename
+    end
+
+    def handler
+      handlers = Praxis::Application.instance.handlers
+      (content_type && handlers[content_type.handler_name]) || handlers['json']
+    end
+
+    def dump(**opts)
+      header_string = self.headers.collect do |name, value|
+        "#{name}: #{value}"
+      end.join("\r\n")
+
+      body = self.payload_attribute.dump(self.payload, **opts)
+
+      body_string = case body
+      when Hash, Array
+        handler.generate(body)
+      else
+        body
+      end
+
+      "#{header_string}\r\n\r\n#{body_string}"
+    end
+
   end
 end