praxis 0.0.1 → 0.9

data/lib/praxis/response_definition.rb

@@ -0,0 +1,264 @@
+
+module Praxis
+  # Response spec DSL container
+
+  class ResponseDefinition
+    attr_reader :name
+
+    def initialize(response_name, **spec, &block)
+      unless response_name
+        raise Exceptions::InvalidConfiguration.new(
+          "Response name is required for a response specification"
+        )
+      end
+      @spec = { headers:{} }
+      @name = response_name
+      self.instance_exec(**spec, &block) if block_given?
+
+      if self.status.nil?
+        raise Exceptions::InvalidConfiguration.new(
+          "Status code is required for a response specification"
+        )
+      end
+    end
+
+    def description(text=nil)
+      return @spec[:description] if text.nil?
+      @spec[:description] = text
+    end
+
+    def status(code=nil)
+      return @spec[:status] if code.nil?
+      @spec[:status] = code
+    end
+
+    def media_type(media_type=nil)
+      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
+          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)
+      return @spec[:location] if loc.nil?
+      unless ( loc.is_a?(Regexp) || loc.is_a?(String) )
+        raise Exceptions::InvalidConfiguration.new(
+          "Invalid location specification. Location in response must be either a regular expression or a string."
+        )
+      end
+      @spec[:location] = loc
+    end
+
+    def headers(hdrs = nil)
+      return @spec[:headers] if hdrs.nil?
+
+      case hdrs
+      when Array
+        hdrs.each {|header_name| header(header_name) }
+      when Hash
+        header(hdrs)
+      when String
+        header(hdrs)
+      else
+        raise Exceptions::InvalidConfiguration.new(
+          "Invalid headers specification: Arrays, Hash, or String must be used. Received: #{hdrs.inspect}"
+        )
+      end
+    end
+
+    def header(hdr)
+      case hdr
+      when String
+        @spec[:headers][hdr] = true
+      when Hash
+        hdr.each do | k, v |
+          unless v.is_a?(Regexp) || v.is_a?(String)
+            raise Exceptions::InvalidConfiguration.new(
+              "Header definitions for #{k.inspect} can only match values of type String or Regexp. Received: #{v.inspect}"
+            )
+          end
+          @spec[:headers][k] = v
+       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}"
+        )
+      end
+    end
+
+    def describe
+      location_type = location.is_a?(Regexp) ? :regexp : :string
+      location_value = location.is_a?(Regexp) ? location.inspect : location
+      content = {
+        :description => description,
+        :status => status,
+        :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
+      unless headers == nil
+        headers.each do |name, value|
+          content[:headers][name] = _describe_header(value) 
+        end
+      end
+      unless parts == nil
+        content[:parts_like] = parts.describe
+      end
+      content
+    end
+
+    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 } 
+    end
+
+    def validate( response )
+      validate_status!(response)
+      validate_location!(response)
+      validate_headers!(response)
+      validate_content_type!(response)
+      validate_parts!(response)
+    end
+
+    def parts(proc=nil, like: nil,  **args, &block)
+      a_proc = proc || block
+      if like.nil? && !a_proc
+        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
+        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
+    end
+
+    # Validates Status code
+    #
+    # @raise [Exceptions::Validation]  When response returns an unexpected status.
+    #
+    def validate_status!(response)
+      return unless status
+      # Validate status code if defined in the spec
+      if response.status != status
+        raise Exceptions::Validation.new(
+          "Invalid response code detected. Response %s dictates status of %s but this response is returning %s." %
+          [name, status.inspect, response.status.inspect]
+        )
+      end
+    end
+
+
+    # Validates 'Location' header
+    #
+    # @raise [Exceptions::Validation] When location header does not match to the defined one.
+    #
+    def validate_location!(response)
+      return if location.nil? || location === response.headers['Location']
+      raise Exceptions::Validation.new("LOCATION does not match #{location.inspect}")
+    end
+
+
+    # Validates Headers
+    #
+    # @raise [Exceptions::Validation]  When there is a missing required header..
+    #
+    def validate_headers!(response)
+      return unless headers
+      headers.each do |name, value|
+        if name.is_a? Symbol
+          raise Exceptions::Validation.new(
+            "Symbols are not supported in headers"
+          )
+        end
+
+        unless response.headers.has_key?(name)
+          raise Exceptions::Validation.new(
+            "Header #{name.inspect} was required but is missing"
+          )
+        end
+
+        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
+          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
+          end
+        end
+      end
+    end
+
+
+    # Validates Content-Type header and response media type
+    #
+    # @param [Object] action
+    #
+    # @raise [Exceptions::Validation] When there is a missing required header
+    #
+    def validate_content_type!(response)
+      return unless media_type
+
+      extracted_identifier = nil
+      if response.headers['Content-Type']
+        extracted_identifier = Praxis::ContentTypeParser.parse(response.headers['Content-Type'])[:type]
+      end
+
+      if media_type.identifier != extracted_identifier
+        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}"
+        )
+      end
+    end
+
+    def validate_parts!(response)
+      return unless parts
+
+      response.parts.each do |name, part|
+        parts.validate(part)
+      end
+
+    end
+
+  end
+end

data/lib/praxis/response_template.rb

@@ -0,0 +1,34 @@
+module Praxis
+
+  class ResponseTemplate
+    attr_reader :name, :block
+
+    def initialize(response_name, &block)
+      @name = response_name
+      @block = block
+    end
+
+    def compile(action=nil, **args)
+      # Default media_type to the resource_definition one, if the block has it in
+      # its required args but no value is passed (funky, but can help in the common case)
+      if block.parameters.any? { |(type, name)| name == :media_type && type == :keyreq } && action
+        unless args.has_key? :media_type
+          media_type = action.resource_definition.media_type
+          unless media_type
+            raise Exceptions::InvalidConfiguration.new(
+              "Could not default :media_type argument for response template #{@name}." +
+               " Resource #{action.resource_definition} does not have an associated mediatype and none was passed"
+            )
+          end
+          args[:media_type] = media_type
+        end
+      end
+      Praxis::ResponseDefinition.new(name, **args, &block)   
+    end
+
+    def describe
+      puts "TODO!!!!!!"
+    end
+  end
+
+end

data/lib/praxis/responses/http.rb

@@ -0,0 +1,166 @@
+module Praxis
+
+  module Responses
+
+    # Standard response for successful HTTP requests. 
+    # The actual response will depend on the request method used. 
+    # In a GET request, the response will contain an entity 
+    # corresponding to the requested resource. 
+    # In a POST request the response will contain an entity 
+    # describing or containing the result of the action.
+    class Ok < Praxis::Response
+      self.status = 200
+    end
+
+
+    # The request has been fulfilled and resulted in a new resource 
+    # being created.
+    class Created < Praxis::Response
+      self.status = 201
+    end
+
+
+    # The request has been accepted for processing, but the 
+    # processing has not been completed. The request might or might 
+    # not eventually be acted upon, as it might be disallowed when 
+    # processing actually takes place.
+    class Accepted < Praxis::Response
+      self.status = 202
+    end
+
+
+    # The server successfully processed the request, but is not returning any content. Usually used as a response to a successful delete request.
+    class NoContent < Praxis::Response
+      self.status = 204
+    end
+
+
+    # Indicates multiple options for the resource that the client may follow. It, for instance, could be used to present different format options for video, list files with different extensions, or word sense disambiguation.
+    class MultipleChoices < Praxis::Response
+      self.status = 300
+    end
+
+
+    # This and all future requests should be directed to the given URI.
+    class MovedPermanently < Praxis::Response
+      self.status = 301
+    end
+
+
+    # This is an example of industry practice contradicting the standard. The HTTP/1.0 specification (RFC 1945) required the client to perform a temporary redirect (the original describing phrase was "Moved Temporarily"),[5] but popular browsers implemented 302 with the functionality of a 303 See Other. Therefore, HTTP/1.1 added self.status = codes 303 and 307 to distinguish between the two behaviours.[6] However, some Web applications and frameworks use the 302 self.status = code as if it were the 303.[7]
+    class Found < Praxis::Response
+      self.status = 302
+    end
+
+
+    # The response to the request can be found under another URI using a GET method. When received in response to a POST (or PUT/DELETE), it should be assumed that the server has received the data and the redirect should be issued with a separate GET message.
+    class SeeOther < Praxis::Response
+      self.status = 303
+    end
+
+
+    # Indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-Match. This means that there is no need to retransmit the resource, since the client still has a previously-downloaded copy.
+    class NotModified < Praxis::Response
+      self.status = 304
+    end
+
+
+    # In this case, the request should be repeated with another URI; however, future requests should still use the original URI. In contrast to how 302 was historically implemented, the request method is not allowed to be changed when reissuing the original request. For instance, a POST request should be repeated using another POST request.[10]
+    class TemporaryRedirect < Praxis::Response
+      self.status = 307
+    end
+
+
+    # The request cannot be fulfilled due to bad syntax.
+    class BadRequest < Praxis::Response
+      self.status = 400
+    end
+
+
+    # Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource. See Basic access authentication and Digest access authentication.
+    class Unauthorized < Praxis::Response
+      self.status = 401
+    end
+
+
+    # The request was a valid request, but the server is refusing to respond to it. Unlike a 401 Unauthorized response, authenticating will make no difference.
+    class Forbidden < Praxis::Response
+      self.status = 403
+    end
+
+
+    # The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
+    class NotFound < Praxis::Response
+      self.status = 404
+    end
+
+
+    # A request was made of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource.
+    class MethodNotAllowed < Praxis::Response
+      self.status = 405
+    end
+
+
+    # A request was made of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource.
+    class NotAcceptable < Praxis::Response
+      self.status = 406
+    end
+
+
+    # Indicates that the request could not be processed because of conflict in the request, such as an edit conflict in the case of multiple updates.
+    class Conflict < Praxis::Response
+      self.status = 409
+    end
+
+
+    # The server does not meet one of the preconditions that the requester put on the request.
+    class PreconditionFailed < Praxis::Response
+      self.status = 412
+    end
+
+
+    # The request was well-formed but was unable to be followed due to semantic errors.[3]
+    class UnprocessableEntity < Praxis::Response
+      self.status = 422
+    end
+
+
+    # A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
+    class InternalServerError < Praxis::Response
+      self.status = 500
+
+      attr_accessor :error
+
+      def initialize(error: nil, **opts)
+        super(**opts)
+        @error = error
+      end
+
+      def format!(exception = @error) #_exception(exception)
+        if @error
+          msg = {
+            name: exception.class.name,
+            message: exception.message,
+            backtrace: exception.backtrace
+          }
+          msg[:cause] = format!(exception.cause) if exception.cause
+          @body = msg
+        end
+      end
+    end
+
+    ApiDefinition.define do |api|
+      self.constants.each do |class_name|
+        response_class = self.const_get(class_name)
+        response_name = response_class.response_name
+        next if api.responses.key?(response_name)
+
+        api.response_template response_name do
+          status response_class.status
+        end
+
+      end
+    end
+
+  end
+end

data/lib/praxis/responses/validation_error.rb

@@ -0,0 +1,36 @@
+module Praxis
+
+  module Responses
+
+    class ValidationError < BadRequest
+      def initialize(errors: nil, exception: nil, **opts)
+        super(**opts)
+        @errors = errors
+        @exception = exception
+      end
+
+      def format!
+        if @errors
+          @body = {name: 'ValidationError', errors: @errors}
+        elsif @exception
+          @body = {name: 'ValidationError', message: @exception.message}
+          if @exception.cause
+            @body[:cause] = {name: @exception.cause.class.name, message: @exception.cause.message}
+          end
+          @body
+        end
+      end
+    end
+
+  end
+
+
+  ApiDefinition.define do |api|
+    api.response_template :validation_error do
+      description "When parameter validation hits..."
+      status 400
+      media_type "application/json"
+    end
+  end
+
+end

data/lib/praxis/route.rb

@@ -0,0 +1,27 @@
+module Praxis
+
+  class Route
+    attr_accessor :verb, :path, :version, :name, :options
+
+    def initialize(verb, path, version='n/a', name:nil, **options)
+      @verb = verb
+      @path = path
+      @version = version
+      @name = name
+      @options = options
+    end
+
+    def describe
+      result = {
+        verb: verb,
+        path: path,
+        version: version
+      }
+      result[:name] = name unless name.nil?
+      result[:options] = options if options.any?
+      result
+    end
+    
+  end
+
+end

data/lib/praxis/router.rb

@@ -0,0 +1,89 @@
+require 'mustermann/router/rack'
+
+module Praxis
+
+  class Router
+    attr_reader :request_class, :application
+
+    class VersionMatcher
+      def initialize(target, version: 'n/a')
+        @target = target
+        @version = version
+      end
+      def call(request)
+        if request.version == @version
+          @target.call(request)
+        else
+          # Version doesn't match, pass and continue
+          request.unmatched_versions << @version
+          throw :pass
+        end
+      end
+    end
+    
+    class RequestRouter < Mustermann::Router::Simple      
+      def initialize(default: nil, **options, &block)
+        options[:default] = :not_found
+
+        super(**options, &block)
+      end
+
+      def invoke(callback, request, params, pattern)
+        request.route_params = params
+        callback.call(request)
+      end
+
+      def string_for(request)
+        request.path
+      end
+    end
+
+
+    def initialize(application, request_class: Praxis::Request)
+      @routes = Hash.new do |hash, verb|
+          hash[verb] = RequestRouter.new
+      end
+      @request_class = request_class
+      @application = application
+    end
+
+    def add_route(target, route)
+      warn 'other conditions not supported yet' if route.options.any?
+      version_wrapper = VersionMatcher.new(target, version: route.version)    
+      @routes[route.verb].on(route.path, call: version_wrapper)
+    end
+
+    def call(env_or_request)
+      request = case env_or_request
+      when Hash
+        request_class.new(env_or_request)
+      when request_class
+        env_or_request
+      else
+        raise ArgumentError, "received #{env_or_request.class}"
+      end
+
+      version = request.version
+      verb = request.verb
+      result = @routes[verb].call(request)
+      if result == :not_found
+        
+        attempted_versions = request.unmatched_versions
+        body = "NotFound"
+        unless attempted_versions.empty? || (attempted_versions.size == 1 && attempted_versions.first == 'n/a')
+          body += if request.version == 'n/a' 
+                    ". Your request did not specify an API version.".freeze 
+                  else 
+                    ". Your request speficied API version = \"#{request.version}\"."
+                  end
+          pretty_versions = attempted_versions.collect(&:inspect).join(', ')
+          body += " Available versions = #{pretty_versions}."
+        end
+        result = [404, {"Content-Type" => "text/plain", }, [body]] 
+      end
+      result
+    end
+
+  end
+
+end

data/lib/praxis/simple_media_type.rb

@@ -0,0 +1,24 @@
+module Praxis
+  
+  SimpleMediaType = Struct.new(:identifier) do
+    def name
+      self.class.name
+    end
+    
+    def ===(other_thing)
+      case other_thing
+      when String
+        identifier == other_thing
+      when MediaType
+        identifier == other_thing.identifier
+      else
+        raise 'can not compare'
+      end
+    end
+
+    def describe(shallow=true)
+      {identifier: identifier}
+    end
+  end
+
+end

data/lib/praxis/skeletor/restful_routing_config.rb

@@ -0,0 +1,45 @@
+module Praxis
+  module Skeletor
+    class RestfulRoutingConfig
+
+      attr_reader :name, :resource_definition, :routes
+
+      def initialize(name, resource_definition, &block)
+        @name = name
+        @resource_definition = resource_definition
+        @routes = []
+
+        @prefix = "/" + resource_definition.name.split("::").last.underscore
+
+        if resource_definition.routing_config
+          instance_eval(&resource_definition.routing_config)
+        end
+
+        instance_eval(&block)
+      end
+
+      def prefix(prefix=nil)
+        return @prefix unless prefix
+        @prefix = prefix
+      end
+
+      def options(path, opts={}) add_route 'OPTIONS', path, opts end
+      def get(path, opts={})     add_route 'GET',     path, opts end
+      def head(path, opts={})    add_route 'HEAD',    path, opts end
+      def post(path, opts={})    add_route 'POST',    path, opts end
+      def put(path, opts={})     add_route 'PUT',     path, opts end
+      def delete(path, opts={})  add_route 'DELETE',  path, opts end
+      def trace(path, opts={})   add_route 'TRACE',   path, opts end
+      def connect(path, opts={}) add_route 'CONNECT', path, opts end
+      def patch(path, opts={})   add_route 'PATCH',   path, opts end
+
+      def add_route(verb, path, options={})
+        path = Mustermann.new(@prefix + path)
+
+        @routes << Route.new(verb, path, resource_definition.version, **options)
+      end
+
+    end
+
+  end
+end