respect-rails 0.1.0

data/lib/respect/rails/info.rb

@@ -0,0 +1,72 @@
+module Respect
+  module Rails
+    # The implementation is strongly inspired from
+    # ActionDispatch::Routing::RoutesInspector.
+    class Info
+
+      def initialize
+        @engines = {}
+        @app = ApplicationInfo.new
+        @app.routes = collect_routes(::Rails.application.routes.routes)
+        @engines[@app.name] = @app
+        @toc = build_toc(self.routes)
+      end
+
+      attr_reader :engines
+      attr_reader :app
+      attr_reader :toc
+
+      def routes
+        @app.routes
+      end
+
+      private
+
+      def collect_routes(routes, mounted_point = nil)
+        result = []
+        routes.each do |route|
+          route = RouteInfo.new(route, mounted_point)
+          next if route.internal?
+          if route.engine?
+            result += collect_engine_routes(route)
+          else
+            if route.has_schema?
+              result << route
+            end
+          end
+        end
+        result
+      end
+
+      def collect_engine_routes(route)
+        return unless route.engine?
+        engine_info = EngineInfo.new(route.endpoint)
+        return if @engines[engine_info.name]
+
+        routes = route.rack_app.routes
+        if routes.is_a?(ActionDispatch::Routing::RouteSet)
+          engine_info.routes = collect_routes(routes.routes, route)
+          @engines[engine_info.name] = engine_info
+          engine_info.routes
+        else
+          []
+        end
+      end
+
+      def build_toc(routes)
+        toc = {}
+        routes.each do |route|
+          next if route.engine?
+          if route.has_schema?
+            controller = route.controller_name
+            action = route.action_name
+            toc[controller] ||= {}
+            toc[controller][action] = route
+          end
+        end
+        toc
+      end
+
+    end # class Info
+  end # module Rails
+end # module Respect

data/lib/respect/rails/request_def.rb

@@ -0,0 +1,38 @@
+module Respect
+  module Rails
+    class RequestDef
+
+      class << self
+        def eval(*args, &block)
+          new(*args).eval(&block)
+        end
+      end
+
+      def initialize(*args)
+        @request_schema = RequestSchema.new(*args)
+      end
+
+      def eval(&block)
+        block.call(self)
+        @request_schema
+      end
+
+      def path_parameters(&block)
+        @request_schema.path_parameters = HashSchema.define(&block)
+      end
+
+      def body_parameters(&block)
+        @request_schema.body_parameters = HashSchema.define(&block)
+      end
+
+      def query_parameters(&block)
+        @request_schema.query_parameters = HashSchema.define(&block)
+      end
+
+      def headers(&block)
+        @request_schema.headers = HashSchema.define(&block)
+      end
+
+    end # class RequestDef
+  end
+end # module Respect

data/lib/respect/rails/request_helper.rb

@@ -0,0 +1,101 @@
+module Respect
+  module Rails
+    module RequestHelper
+      extend ActiveSupport::Concern
+
+      # Return whether this request validates the schema.
+      # You can get the validation error via {#last_validation_error}.
+      def validate_schema?
+        begin
+          validate_schema
+        rescue Respect::Rails::RequestValidationError
+          false
+        end
+      end
+
+      # Raise a {Respect::Rails::RequestValidationError} exception if this
+      # request does not validate the schema.
+      def validate_schema
+        log_msg = "  Request validation: "
+        @validated = nil
+        measure = Benchmark.realtime do
+          @validated = request_schema.validate?(self) unless request_schema.nil?
+        end
+        if @validated.nil?
+          log_msg += "none"
+        else
+          if @validated == true
+            log_msg += "success"
+          else
+            log_msg += "failure"
+          end
+        end
+        log_msg += " (%.1fms)" % [ measure * 1000 ]
+        ::Rails.logger.info log_msg
+        if @validated == false
+          last_validation_error.context.each do |msg|
+            ::Rails.logger.info "    #{msg}"
+          end
+          raise last_validation_error
+        end
+        true
+      end
+
+      def response_schema(http_status)
+        unless action_schema.nil? || action_schema.responses.nil?
+          action_schema.responses[http_status]
+        end
+      end
+
+      def request_schema
+        action_schema.request if action_schema
+      end
+
+      attr_reader :action_schema
+      attr_writer :action_schema
+      private :action_schema=
+
+      def has_schema?
+        !!action_schema
+      end
+
+      def last_validation_error
+        request_schema.last_error
+      end
+
+      # Returns the sanitized parameters if the schema validation has succeed.
+      def sane_params
+        request_schema.sanitized_params if request_schema
+      end
+
+      # Returns +nil+ if never validated, +true+ if validated successfully and
+      # +false+ if validation failed.
+      def validated
+        @validated
+      end
+
+      # Returns +true+ if the validation has been done and succeed and +false+
+      # otherwise.
+      def validated?
+        !!validated
+      end
+
+      # Sanitize all the request's parameters (path, query and body) *in-place*.
+      # if the schema validation has succeed. Validate it first if it has not
+      # been yet.
+      def sanitize_params!
+        if request_schema
+          if validated.nil?
+            validate_schema
+          end
+          if validated?
+            request_schema.sanitize!(self)
+          end
+        end
+      end
+
+    end # module RequestHelper
+  end # module Rails
+end # module Respect
+
+ActionDispatch::Request.send :include, Respect::Rails::RequestHelper

data/lib/respect/rails/request_schema.rb

@@ -0,0 +1,102 @@
+module Respect
+  module Rails
+    class RequestSchema
+      include HeadersSimplifier
+
+      class << self
+        def define(*args, &block)
+          RequestDef.eval(*args, &block)
+        end
+      end
+
+      def initialize(controller, action)
+        @controller = controller
+        @action = action
+        @default_path_parameters = HashSchema.define do |s|
+          s.string "controller", equal_to: @controller.to_s, doc: false
+          s.string "action", equal_to: @action.to_s, doc: false
+        end
+        @path_parameters = @default_path_parameters.dup
+        @body_parameters = HashSchema.new
+        @query_parameters = HashSchema.new
+        @headers = HashSchema.new
+      end
+
+      attr_reader :controller, :action
+
+      attr_accessor :headers
+
+      attr_accessor :body_parameters, :query_parameters
+
+      attr_reader :path_parameters, :default_path_parameters
+
+      # Merge +path_parameters+ with {#default_path_parameters} and store it.
+      def path_parameters=(path_parameters)
+        @path_parameters = @default_path_parameters.merge(path_parameters)
+      end
+
+      attr_reader :sanitized_params
+
+      # Validate the given +request+.
+      # Raise a {RequestValidationError} if an error occur.
+      # Returns +true+ on success.
+      def validate(request)
+        # Validate requests.
+        unless Respect::Rails::Engine.disable_request_headers_validation
+          begin
+            headers.validate(request.headers)
+          rescue Respect::ValidationError => e
+            raise RequestValidationError.new(e, :headers, simplify_headers(request.headers))
+          end
+        end
+        [ :path, :query, :body ].each do |name|
+          begin
+            send("#{name}_parameters").validate(request.params)
+          rescue Respect::ValidationError => e
+            raise RequestValidationError.new(e, name, request.params)
+          end
+        end
+        # Build sane parameters.
+        @sanitized_params = {}
+        [ :path, :query, :body ].each do |name|
+          @sanitized_params.merge!(send("#{name}_parameters").sanitized_object)
+        end
+        true
+      end
+
+      def validate?(request)
+        begin
+          validate(request)
+          true
+        rescue RequestValidationError => e
+          @last_error = e
+          false
+        end
+      end
+
+      # Return the last validation error that happens during the
+      # validation process. (set by {#validate?})
+      # Reset each time {#validate?} is called.
+      attr_reader :last_error
+
+      # Validate the request and sanitize its parameters if the validation succeed.
+      # You can disable the sanitization with
+      # {Respect::Rails::Engine.sanitize_request_parameters}.
+      def validate!(request)
+        valid = validate?(request)
+        if valid
+          sanitize!(request)
+        end
+        valid
+      end
+
+      # Sanitize all the request's parameters (path, query and body) *in-place*.
+      def sanitize!(request)
+        [ :path, :query, :body ].each do |name|
+          send("#{name}_parameters").sanitize_object!(request.params)
+        end
+      end
+
+    end
+  end
+end

data/lib/respect/rails/response_def.rb

@@ -0,0 +1,43 @@
+module Respect
+  module Rails
+    class ResponseDef
+
+      class << self
+        def eval(*args, &block)
+          new(*args).eval(&block)
+        end
+      end
+
+      def initialize(*args)
+        @response_schema = ResponseSchema.new(*args)
+      end
+
+      def eval(&block)
+        block.call(self)
+        @response_schema
+      end
+
+      # Define the schema of the response body.
+      # @option options [Boolean] hash (true) whether the body is hash schema.
+      def body(options = {}, &block)
+        @response_schema.body = (
+          if options.fetch(:hash, true)
+            HashSchema.define(&block)
+          else
+            Schema.define(&block)
+          end
+          )
+      end
+
+      def headers(options = {}, &block)
+        @response_schema.headers = HashSchema.define(options, &block)
+      end
+
+      # Set the documentation to +text+.
+      def documentation(text)
+        @response_schema.documentation = text
+      end
+
+    end # class ResponseDef
+  end # module Rails
+end # module Respect

data/lib/respect/rails/response_helper.rb

@@ -0,0 +1,67 @@
+module Respect
+  module Rails
+    module ResponseHelper
+      extend ActiveSupport::Concern
+
+      attr_reader :schema
+      attr_writer :schema
+      private :schema=
+
+      def has_schema?
+        !!@schema
+      end
+
+      # Return whether this response validates the schema.
+      # You can get the validation error via {#last_validation_error}.
+      def validate_schema?
+        begin
+          validate_schema
+        rescue Respect::Rails::ResponseValidationError => e
+          false
+        end
+      end
+
+      # Raise a {Respect::Rails::ResponseValidationError} exception if this
+      # response does not validate the schema.
+      def validate_schema
+        log_msg = "  Response validation: "
+        valid = nil
+        measure = Benchmark.realtime do
+          if schema && content_type == Mime::JSON
+            valid = schema.validate?(self)
+          end
+        end
+        if valid.nil?
+          log_msg += "none"
+        else
+          if valid
+            log_msg += "success"
+          else
+            log_msg += "failure"
+          end
+        end
+        log_msg += " (%.1fms)" % [ measure * 1000 ]
+        ::Rails.logger.info log_msg
+        if valid == false
+          last_validation_error.context.each do |msg|
+            ::Rails.logger.info "    #{msg}"
+          end
+          if Respect::Rails::Engine.catch_response_validation_error
+            self.body = last_validation_error.to_json
+            self.status = :internal_server_error
+          else
+            raise last_validation_error
+          end
+        end
+        true
+      end
+
+      def last_validation_error
+        schema.last_error
+      end
+
+    end # module ResponseHelper
+  end # module Rails
+end # module Respect
+
+ActionDispatch::Response.send :include, Respect::Rails::ResponseHelper

data/lib/respect/rails/response_schema.rb

@@ -0,0 +1,84 @@
+module Respect
+  module Rails
+    class ResponseSchema
+      include HeadersSimplifier
+      include Respect::DocHelper
+
+      class << self
+
+        def http_status(status)
+          Rack::Utils.status_code(status)
+        end
+
+        # FIXME(Nicolas Despres): Move me to another module/class.
+        def symbolize_http_status(http_status)
+          h = Rack::Utils::HTTP_STATUS_CODES
+          (h[http_status] || h[500]).downcase.gsub(/\s|-/, '_').to_sym
+        end
+
+        def define(*args, &block)
+          ResponseDef.eval(*args, &block)
+        end
+
+        # Read the response schema definition from the given +filename+ and
+        # evaluate it as a block passed to {ResponseSchema.define}
+        def from_file(status, filename)
+          define(status) do |r|
+            r.instance_eval(File.read(filename), filename)
+          end
+        end
+      end
+
+      def initialize(status = :ok)
+        @status = status
+        @headers = HashSchema.new
+      end
+
+      attr_reader :status
+
+      def http_status
+        self.class.http_status(@status)
+      end
+
+      attr_accessor :body
+
+      def ==(other)
+        @status == other.status && @body == other.body
+      end
+
+      def validate(response)
+        if headers
+          begin
+            headers.validate(response.headers)
+          rescue Respect::ValidationError => e
+            raise Respect::Rails::ResponseValidationError.new(e, :headers, simplify_headers(response.headers))
+          end
+        end
+        if body
+          decoded_body = ActiveSupport::JSON.decode(response.body)
+          begin
+            body.validate(decoded_body)
+          rescue Respect::ValidationError => e
+            raise Respect::Rails::ResponseValidationError.new(e, :body, decoded_body)
+          end
+        end
+        true
+      end
+
+      def validate?(response)
+        begin
+          validate(response)
+          true
+        rescue Respect::Rails::ResponseValidationError => e
+          @last_error = e
+          false
+        end
+      end
+
+      attr_reader :last_error
+
+      attr_accessor :headers
+      attr_accessor :documentation
+    end
+  end
+end

data/lib/respect/rails/response_schema_set.rb

@@ -0,0 +1,60 @@
+module Respect
+  module Rails
+    class ResponseSchemaSet
+
+      class << self
+        # FIXME(Nicolas Despres): Move me to another module/class.
+        def symbolize_status(status)
+          case status
+          when Symbol
+            status
+          when String
+            if status =~ /^\d+$/
+              symbolize_status(status.to_i)
+            else
+              status.to_sym
+            end
+          when Numeric
+            ResponseSchema.symbolize_http_status(status.to_i)
+          else
+            raise ArgumentError, "cannot normalize status '#{status}:#{status.class}'"
+          end
+        end
+      end
+
+      # Initialize a new ResponseSchemaSet object for the given controller's
+      # action and collect response' schema from their respective file.
+      def initialize(controller_name, action_name)
+        @controller_name = controller_name
+        @action_name = action_name
+        @set = {}
+      end
+
+      attr_reader :controller_name, :action_name
+
+      def method_missing(method_name, *arguments, &block)
+        define_response(method_name, *arguments, &block)
+      end
+
+      def [](http_status)
+        @set[http_status]
+      end
+
+      delegate :each, :empty?, to: :@set
+
+      def <<(response_schema)
+        @set[response_schema.http_status] = response_schema
+      end
+
+      def is(status, *arguments, &block)
+        define_response(status, *arguments, &block)
+      end
+
+      def define_response(status, *arguments, &block)
+        status = self.class.symbolize_status(status)
+        self << ResponseSchema.define(status, *arguments, &block)
+      end
+
+    end
+  end # module Rails
+end # module Respect

data/lib/respect/rails/route_info.rb

@@ -0,0 +1,101 @@
+module Respect
+  module Rails
+    # A wrapper around ActionDispatch::Routing::Route. It provides only
+    # access to the information we need when generating doc.
+    # It is very strongly inspired from ActionDispatch::Routing::RouteWrapper class
+    # which is internal and designed to be used with
+    # ActionDispoatch::Routing::RouteInspector. These classes are not meant
+    # to be used by external user as far as I can read in rails code base.
+    # So, we made up our own so that we can easily adjust it to our need.
+    class RouteInfo
+      include Comparable
+
+      def initialize(route, mount_point)
+        @route = route
+        if !mount_point.is_a?(self.class) && !mount_point.nil? && !mount_point.engine?
+          raise "'#{mount_point.inspect}' must be a route to an engine if set"
+        end
+        @mount_point = mount_point
+      end
+
+      attr_reader :route, :mount_point
+
+      def path
+        path = @route.path.spec.to_s
+        if @mount_point
+          path = @mount_point.path + path
+        end
+        if path.length > 1 && path =~ %r{/$}
+          path.chop!
+        end
+        path
+      end
+
+      def internal?
+        path =~ %r{\A#{::Rails.application.config.assets.prefix}} \
+        || controller_name =~ %r{\Arails/(info|welcome)}
+      end
+
+      def <=>(other)
+        self.path <=> other.path
+      end
+
+      def verb
+        @route.verb.source.gsub(/[$^]/, '')
+      end
+
+      def controller_name
+        @route.requirements[:controller] || ':controller'
+      end
+
+      def action_name
+        @route.requirements[:action] || ':action'
+      end
+
+      def schema
+        @schema = ActionSchema.from_controller(controller_name, action_name)
+      end
+
+      def has_schema?
+        schema && schema.has_schema?
+      end
+
+      def spec
+        "#{verb} #{path}".strip
+      end
+
+      def url
+        if schema
+          options = schema_set.default_url_options
+        else
+          options = @route.defaults.merge({ format: 'json' })
+        end
+        ::Rails.application.routes.url_for(options)
+      end
+
+      def endpoint
+        rack_app ? rack_app : nil
+      end
+
+      def rack_app(app = @route.app)
+        @rack_app ||= begin
+          class_name = app.class.name.to_s
+          if class_name == "ActionDispatch::Routing::Mapper::Constraints"
+            rack_app(app.app)
+          elsif ActionDispatch::Routing::Redirect === app || class_name !~ /^ActionDispatch::Routing/
+            app
+          end
+        end
+      end
+
+      def engine?
+        rack_app && rack_app.respond_to?(:routes)
+      end
+
+      def anchor
+        "#{controller_name}_#{action_name}"
+      end
+
+    end # class RouteInfo
+  end # module Rails
+end # module Respect

data/lib/respect/rails/version.rb

@@ -0,0 +1,5 @@
+module Respect
+  module Rails
+    VERSION = "0.1.0"
+  end
+end