rails-param-validation 0.1.0

data/lib/rails-param-validation/rails/action_definition.rb

@@ -0,0 +1,66 @@
+module RailsParamValidation
+
+  class ActionDefinition
+    attr_reader :params, :request_body_type, :paths, :responses, :controller, :action
+    attr_accessor :description
+
+    def initialize
+      @params = {}
+      @paths = []
+      @param_validation_enabled = true
+      @description = ''
+      @request_body_type = RailsParamValidation.config.default_body_content_type if defined?(Rails)
+      @responses = {}
+    end
+
+    def store_origin!(controller, action)
+      @controller = controller
+      @action = action
+    end
+
+    def disable_param_validation!
+      @param_validation_enabled = false
+    end
+
+    def param_validation?
+      @param_validation_enabled
+    end
+
+    def request_body_type!(mime)
+      @request_body_type = mime
+    end
+
+    def add_param(name, type, schema, description)
+      @params[name] = {
+          schema: schema,
+          description: description,
+          type: type
+      }
+    end
+
+    def add_response(status, schema, description)
+      @responses[status] = {
+          schema: schema,
+          description: description
+      }
+    end
+
+    def add_path(method, path)
+      @paths.push(method: method, path: path)
+    end
+
+    def finalize!(class_name, method_name)
+      @responses.each do |code, response|
+        name = "#{class_name.to_s.capitalize}#{method_name.to_s.camelcase}#{Rack::Utils::SYMBOL_TO_STATUS_CODE.key(code).to_s.camelize}Response".to_sym
+        AnnotationTypes::CustomT.register(name, response[:schema])
+
+        response.merge!(schema: AnnotationTypes::CustomT.new(name))
+      end
+    end
+
+    def to_schema
+      @params.map { |k, v| [k, v[:schema]] }.to_h
+    end
+  end
+
+end

data/lib/rails-param-validation/rails/annotation_manager.rb

@@ -0,0 +1,40 @@
+module RailsParamValidation
+
+  class AnnotationManager
+    attr_reader :annotations
+    def initialize
+      @annotations = {}
+    end
+
+    def self.instance
+      @instance ||= AnnotationManager.new
+    end
+
+    def classes
+      @annotations.keys
+    end
+
+    def methods(klass)
+      @annotations.fetch(klass, {}).keys
+    end
+
+    def annotate_method!(klass, method_name, type, value)
+      @annotations[klass.name] ||= {}
+      @annotations[klass.name][method_name] ||= {}
+      @annotations[klass.name][method_name][type] = value
+    end
+
+    def method_annotation(class_name, method_name, type)
+      @annotations.fetch(class_name, {}).fetch(method_name, {}).fetch(type, nil)
+    end
+
+    def annotate_class!(klass, type, value)
+      annotate_method! klass, '', type, value
+    end
+
+    def class_annotation(class_name, type)
+      method_annotation class_name, '', type
+    end
+  end
+
+end

data/lib/rails-param-validation/rails/config.rb

@@ -0,0 +1,48 @@
+module RailsParamValidation
+
+  class OpenApiMetaConfig
+    attr_accessor :title, :version, :url, :description
+
+    def initialize
+      app_class = Rails.application.class
+
+      self.url = 'http://localhost:3000'
+      self.title = app_name(app_class)
+      self.version = '1.0'
+      self.description = "#{app_name(app_class)} application"
+    end
+
+    private
+
+    def app_name(klass)
+      return klass.module_parent_name if klass.respond_to? :module_parent_name
+      klass.parent.name
+    end
+  end
+
+  class Configuration
+    attr_accessor :use_default_json_response
+    attr_accessor :use_default_html_response
+    attr_accessor :use_validator_caching
+    attr_accessor :raise_on_missing_annotation
+    attr_accessor :default_body_content_type
+    attr_reader   :openapi
+
+    def initialize
+      @use_default_json_response = true
+      @use_default_html_response = true
+      @use_validator_caching = Rails.env.production?
+      @raise_on_missing_annotation = true
+      @default_body_content_type = 'application/json'
+    end
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  def self.openapi
+    @openapi ||= OpenApiMetaConfig.new
+  end
+
+end

data/lib/rails-param-validation/rails/extensions/annotation_extension.rb

@@ -0,0 +1,95 @@
+require_relative './../action_definition'
+require_relative './../annotation_manager'
+
+module RailsParamValidation
+  module AnnotationExtension
+
+    def self.included(klass)
+      klass.extend ClassMethods
+
+      # Check if there already is a method_added implementation
+      begin
+        existing_method_added = klass.method(:method_added)
+      rescue NameError => e
+        existing_method_added = nil
+      end
+
+      klass.define_singleton_method(:method_added) do |name|
+        # If there is a parameter definition: annotate this method and reset the carrier variable
+        if @param_definition
+          # Store where this annotation came from
+          class_name = RailsHelper.controller_to_tag self
+          method_name = name.to_sym
+
+          @param_definition.store_origin! class_name, method_name
+          @param_definition.finalize! class_name, method_name
+
+          AnnotationManager.instance.annotate_method! self, name, :param_definition, @param_definition
+          @param_definition = nil
+
+          # Parameter wrapping needs to be disabled
+          wrap_parameters false if respond_to? :wrap_parameters
+        end
+
+        # If there already was an existing method_added implementation, call it
+        existing_method_added&.call(name)
+      end
+    end
+
+    module ClassMethods
+      def param_definition
+        @param_definition || raise(StandardError.new "Annotation must be part of an operation-block")
+      end
+
+      # @param [Symbol] name Name of the parameter as it is accessible by params[<name>]
+      # @param schema Definition of the schema (according to the available validators)
+      # @param [String] description Description of the param, just for documentation
+      def param(name, schema, type = :query, description = nil)
+        param_definition.add_param name, type, schema, description
+      end
+
+      def query_param(name, schema, description = nil)
+        param name, schema, :query, description
+      end
+
+      def body_param(name, schema, description = nil)
+        param name, schema, :body, description
+      end
+
+      def path_param(name, schema, description = nil)
+        param name, schema, :path, description
+      end
+
+      def body_type(mime_type)
+        param_definition.request_body_type! mime_type
+      end
+
+      def desc(description)
+        if @param_definition
+          param_definition.description = description
+        else
+          AnnotationManager.instance.annotate_class! self, :description, description
+        end
+      end
+
+      def no_params
+        param_definition
+      end
+
+      def accept_all_params
+        param_definition.disable_param_validation!
+      end
+
+      def response(status, schema, description)
+        param_definition.add_response status, schema, description
+      end
+
+      def action(description = nil)
+        @param_definition = ActionDefinition.new
+        @param_definition.description = description
+
+        yield
+      end
+    end
+  end
+end

data/lib/rails-param-validation/rails/extensions/custom_type_extension.rb

@@ -0,0 +1,13 @@
+module RailsParamValidation
+  module CustomTypesExtension
+    def self.included(klass)
+      klass.extend ClassMethods
+    end
+
+    module ClassMethods
+      def declare(type, schema)
+        RailsParamValidation::AnnotationTypes::CustomT.register type, schema
+      end
+    end
+  end
+end

data/lib/rails-param-validation/rails/extensions/error.template.html.erb

@@ -0,0 +1,86 @@
+<html lang="en">
+<head>
+  <style type="text/css">
+    body {
+      font-family: Arial, Helvetica, sans-serif;
+      background-color: #e8e8e8;
+      font-size: 11pt;
+      height: calc(100% - 20px);
+      padding: 10px;
+      margin: 0;
+    }
+
+    .content {
+      display: flex;
+      height: 100%;
+    }
+
+    .box {
+      background-color: white;
+      padding-left: 20px;
+      padding-right: 20px;
+      padding-bottom: 20px;
+      border-radius: 3px;
+      max-width: 400px;
+      margin: 50px auto auto;
+
+      -webkit-box-shadow: 0 0 10px 1px rgba(0,0,0,0.5);
+      -moz-box-shadow: 0 0 10px 1px rgba(0,0,0,0.5);
+      box-shadow: 0 0 10px 1px rgba(0,0,0,0.5);
+    }
+
+    .headline {
+      margin-top: 15px;
+      margin-left: -20px;
+      margin-right: -20px;
+      padding: 10px 20px;
+      background-color: #660000;
+      text-align: center;
+    }
+
+    .description {
+      font-size: small;
+      color: #606060;
+    }
+
+    h1 {
+      color: white;
+      font-size: 12pt;
+      margin: 0;
+    }
+
+    .path {
+      font-weight: bold;
+      font-size: small;
+      padding-right: 20px;
+    }
+
+    .message {
+      font-size: small;
+    }
+
+    td {
+      padding-bottom: 5px;
+    }
+  </style>
+  <title>Bad Request</title>
+</head>
+<body>
+<div class="content">
+  <div class="box">
+    <div class="headline">
+      <h1>Invalid Parameters</h1>
+    </div>
+    <p class="description">The request was invalid because the validation of the parameters has failed for the following reasons:</p>
+    <table>
+        <% result.errors.each do |error| %>
+        <tr>
+          <td class="path"><%= error[:path].join(' / ') %></td>
+          <td class="message"><%= error[:message] %></td>
+        </tr>
+        <% end %>
+    </table>
+  </div>
+</div>
+</body>
+</html>

data/lib/rails-param-validation/rails/extensions/validation_extension.rb

@@ -0,0 +1,105 @@
+module RailsParamValidation
+  module ActionControllerExtension
+    def self.included(klass)
+      klass.send(:before_action, :auto_validate_params!)
+    end
+
+    # The before_action function called which does the actual work
+    def auto_validate_params!
+      # @type [ActionDefinition] definition
+      definition = RailsParamValidation::AnnotationManager.instance.method_annotation self.class.name, action_name.to_sym, :param_definition
+
+      if definition.nil?
+        if RailsParamValidation.config.raise_on_missing_annotation
+          raise RailsParamValidation::MissingParameterAnnotation.new
+        else
+          return
+        end
+      end
+
+      return unless definition.param_validation?
+
+      parameters = {}
+      params.each do |param, value|
+        # The params array contains the name and the controller, so we need to remove it
+        if param == 'action' || param == 'controller'
+          next
+        end
+
+        # Convert ActionController::Parameters to a normal hash
+        parameters[param.to_s] = _to_hash_type value
+      end
+
+      action = params['action']
+      controller = params['controller']
+
+      validator = _validator_from_schema controller, action, definition.to_schema
+      result = validator.matches?([], parameters)
+
+      if result.matches?
+        # Copy the parameters if the validation succeeded
+        @validated_parameters = result.value
+      else
+        # Render an appropriate error message
+        _render_invalid_param_response result
+      end
+    end
+
+    def params
+      @validated_parameters || super
+    end
+
+    def _render_invalid_param_response(result)
+      # Depending on the accept header, choose the way to answer
+      respond_to do |format|
+        format.html do
+          if RailsParamValidation.config.use_default_html_response
+            _create_html_error result
+          else
+            raise ParamValidationFailedError.new(result)
+          end
+        end
+        format.json do
+          if RailsParamValidation.config.use_default_json_response
+            _create_json_error result
+          else
+            raise ParamValidationFailedError.new(result)
+          end
+        end
+      end
+    end
+
+    # Create an empty object as JSON response
+    def _create_json_error(result)
+      render json: { status: :fail, errors: result.error_messages }, status: :bad_request
+    end
+
+    # Create an empty html error page
+    def _create_html_error(result)
+      @@_param_html_error_template ||= File.read(File.dirname(__FILE__) + '/error.template.html.erb')
+      render html: ERB.new(@@_param_html_error_template).result(binding).html_safe, status: :bad_request
+    end
+
+    # Convert params to "normal" types
+    def _to_hash_type(params)
+      return params.map(&method(:_to_hash_type)) if params.is_a?(Array)
+      return params.keys.map { |k| [k, _to_hash_type(params[k])] }.to_h if params.is_a?(ActionController::Parameters)
+
+      params
+    end
+
+    # @return [Validator]
+    def _validator_from_schema(controller, method, schema)
+      unless RailsParamValidation.config.use_validator_caching
+        return RailsParamValidation::ValidatorFactory.create schema
+      end
+
+      # Setup static key if it doesn't already exist
+      @@cache ||= {}
+
+      # Create and/or return validator
+      @@cache["#{controller}##{method}"] ||= RailsParamValidation::ValidatorFactory.create schema
+    end
+  end
+end
+

data/lib/rails-param-validation/rails/helper.rb

@@ -0,0 +1,9 @@
+module RailsParamValidation
+
+  class RailsHelper
+    def self.controller_to_tag(klass)
+      (klass.is_a?(String) ? klass : klass.name).gsub(/Controller$/, '').to_sym
+    end
+  end
+
+end

data/lib/rails-param-validation/rails/openapi/openapi.rb

@@ -0,0 +1,128 @@
+require 'uri'
+
+require_relative './routing_helper'
+
+module RailsParamValidation
+
+  class OpenApi
+    OPENAPI_VERSION = "3.0.0"
+
+    def initialize(title, version, url, description)
+      @info = {
+          title: title, version: version,
+          description: description,
+          url: [url], basePath: URI(url).path
+      }
+
+      @actions = []
+      @tags = {}
+
+      load_from_annotations
+    end
+
+    def to_object
+      object = {
+        openapi: OPENAPI_VERSION,
+        info: { version: @info[:version], title: @info[:title], description: @info[:description] },
+        servers: @info[:url].map { |url| { url: url } },
+        tags: @tags.map { |tag, description| { name: tag, description: description } },
+        paths: {},
+        components: { schemas: {} }
+      }
+
+      @actions.each do |operation|
+        body = operation.params.filter { |_, v| v[:type] == :body }.map { |name, pd| [name, pd[:schema]] }.to_h
+
+        parameters = operation.params.filter { |_, v| v[:type] != :body }.map do |name, pd|
+          param_definition = { name: name, in: pd[:type] }
+          if pd[:description].present?
+            param_definition[:description] = pd[:description]
+          end
+
+          validator = RailsParamValidation::ValidatorFactory.create pd[:schema]
+          param_definition[:required] = true unless validator.is_a? RailsParamValidation::OptionalValidator
+          param_definition[:schema] = validator.to_openapi
+
+          param_definition
+        end
+
+        RoutingHelper.routes_for(operation.controller.to_s.underscore, operation.action.to_s).each do |route|
+          action_definition = {
+              operationId: "#{route[:method].downcase}#{route[:path].split(/[^a-zA-Z0-9]+/).map(&:downcase).map(&:capitalize).join}",
+              tags: [operation.controller],
+              parameters: parameters,
+              responses: operation.responses.map do |status, values|
+                [
+                    status.to_s,
+                    {
+                        description: values[:description],
+                        content: {
+                            operation.request_body_type => {
+                                schema: ValidatorFactory.create(values[:schema]).to_openapi
+                            }
+                        }
+                    }
+                ]
+              end.to_h
+          }
+
+          action_definition.merge!(summary: operation.description) if operation.description.present?
+
+          if body.any?
+            body_type_name = "#{operation.controller.capitalize}#{operation.action.capitalize}Body".to_sym
+            AnnotationTypes::CustomT.register(body_type_name, body)
+
+            action_definition[:requestBody] = {
+                content: {
+                    operation.request_body_type => {
+                        schema: ValidatorFactory.create(AnnotationTypes::CustomT.new(body_type_name)).to_openapi
+                    }
+                }
+            }
+          end
+
+          object[:paths][route[:path]] ||= {}
+          object[:paths][route[:path]][route[:method].downcase.to_sym] = action_definition
+        end
+      end
+
+      AnnotationTypes::CustomT.types.each do |name|
+        object[:components][:schemas][name] = ValidatorFactory.create(AnnotationTypes::CustomT.registered(name)).to_openapi
+      end
+
+      stringify_values object
+    end
+
+    protected
+
+    def load_from_annotations
+      AnnotationManager.instance.classes.each do |klass|
+        description = AnnotationManager.instance.class_annotation klass, :description
+
+        if description
+          @tags[RailsHelper.controller_to_tag klass] = description
+        end
+
+        AnnotationManager.instance.methods(klass).each do |method|
+          params = AnnotationManager.instance.method_annotation klass, method, :param_definition
+          next if params.nil?
+
+          @actions.push params
+        end
+      end
+    end
+
+    def stringify_values(object)
+      if object.is_a? Hash
+        return object.map { |k, v| [stringify_values(k), stringify_values(v)] }.to_h
+      elsif object.is_a? Array
+        return object.map { |k| stringify_values k }
+      elsif object.is_a? Symbol
+        return object.to_s
+      else
+        return object
+      end
+    end
+  end
+
+end

data/lib/rails-param-validation/rails/openapi/routing_helper.rb

@@ -0,0 +1,40 @@
+module RailsParamValidation
+  class Formatter < ActionDispatch::Journey::Visitors::FunctionalVisitor
+    def binary(node, seed)
+      visit(node.right, visit(node.left, seed))
+    end
+
+    def nary(node, seed)
+      node.children.inject(seed) { |s, c| visit(c, s) }
+    end
+
+    def terminal(node, seed)
+      seed.map { |s| s + node.left }
+    end
+
+    def visit_GROUP(node, seed)
+      visit(node.left, seed.dup) + seed
+    end
+
+    def visit_SYMBOL(node, seed)
+      name = node.left
+      name = name[1..-1] if name[0] == ":"
+      seed.map { |s| s + "{#{name}}" }
+    end
+  end
+
+  class RoutingHelper
+    def self.routes_for(controller, action)
+      routes = []
+      Rails.application.routes.routes.each do |route|
+        if route.defaults[:controller] == controller && route.defaults[:action] == action
+          Formatter.new.accept(route.path.ast, [""]).each do |path|
+            routes.push(path: path, method: route.verb)
+          end
+        end
+      end
+
+      routes
+    end
+  end
+end

data/lib/rails-param-validation/rails/rails.rb

@@ -0,0 +1,31 @@
+require_relative './extensions/validation_extension'
+require_relative './extensions/annotation_extension'
+require_relative './extensions/custom_type_extension'
+
+require_relative './openapi/openapi'
+
+require_relative '../errors/param_validation_failed_error'
+require_relative '../errors/missing_parameter_annotation'
+require_relative '../errors/type_not_found'
+
+require_relative './config'
+require_relative './helper'
+
+module RailsParamValidation
+  class Railtie < Rails::Railtie
+    railtie_name :param_validation
+
+    initializer 'rails_param_validation.action_controller_extension' do
+      ActionController::Base.send :include, ActionControllerExtension
+      ActionController::Base.send :include, AnnotationExtension
+      ActionController::Base.send :include, CustomTypesExtension
+      ActionController::Base.send :extend, RailsParamValidation::Types
+    end
+
+    rake_tasks do
+      path = File.expand_path(__dir__)
+      Dir.glob("#{path}/tasks/**/*.rake").each { |f| load f }
+    end
+  end
+end
+

data/lib/rails-param-validation/rails/tasks/openapi.rake

@@ -0,0 +1,32 @@
+namespace :openapi do
+
+  desc "Export OpenAPI definition to to openapi.yaml"
+  task export: :environment do
+    # Ensure all controllers are loaded
+    if defined? Zeitwerk
+      # Due to a regression using rails 6 (https://github.com/rails/rails/issues/37006),
+      # we need to call zeitwerk explicitly
+      Zeitwerk::Loader.eager_load_all
+    else
+      Rails.application.eager_load!
+    end
+
+    openapi = RailsParamValidation::OpenApi.new(
+        RailsParamValidation.openapi.title,
+        RailsParamValidation.openapi.version,
+        RailsParamValidation.openapi.url,
+        RailsParamValidation.openapi.description
+    )
+
+    filename = Rails.root.join("openapi.yaml").to_s
+    print "Writing #{filename}..."
+
+    begin
+      File.open(filename, "w") { |f| f.write YAML.dump(openapi.to_object) }
+      puts " done."
+    rescue Exception => e
+      puts " failed."
+      raise e
+    end
+  end
+end