pastore 0.0.4 → 0.2.0

data/docs/Params.md

@@ -0,0 +1,122 @@
+# `Pastore::Params`
+
+`Pastore::Params` is the module that provides the features for params validation in Rails controllers. It allows you to define the params with their data type (`string`, `number`, `boolean`, `date` and `object`), specify which params are mandatory and cannot be blank.
+
+**Table of Contents**
+
+- [`Pastore::Params`](#pastoreparams)
+  - [Setup](#setup)
+  - [Specifying params](#specifying-params)
+    - [Available param types](#available-param-types)
+    - [Avaliable options](#avaliable-options)
+
+## Setup
+
+To start using `Pastore::Params` you just need to include `Pastore::Params` module in your controller. If you plan to use it in all your controllers, just add the following to your `ApplicationController` class:
+
+```ruby
+# app/controllers/application_controller.rb
+
+class ApplicationController < ActionController::API
+  include Pastore::Params
+
+  # Specify response status code to use for invalid params (default: unprocessable_entity)
+  invalid_params_status :bad_request
+
+  # Here you can customize the response to return on invalid params
+  on_invalid_params do
+    render json: { message: 'Invalid params' }
+  end
+
+  # ...
+end
+```
+
+## Specifying params
+
+Once you have configured `Pastore::Params` in your controller you can use the `param` method to define your params.
+
+`param` method has the following signature:
+
+```ruby
+param PARAM_NAME, **OPTIONS
+```
+
+`PARAM_NAME` can be a `String` or a `Symbol`, while `OPTIONS` is a `Hash`.
+
+Below you can find some examples of params definition using `param` method:
+
+```ruby
+class UsersController < ApplicationController
+  # specify that :query param is a string, so that it will automatically be converted to string
+  param :query, type: :string
+  # specify that :page param is a number, which will be defaulted to 1 and will have 1 as lower limit
+  param :page, type: :number, default: 1, min: 1
+  # specify that :per_page param is a number, which will be defaulted to 15 and will enforce the value to be in a range between 1 and 200
+  param :per_page, type: :number, default: 15, clamp: 1..200
+  def index
+    # ... your code ...
+  end
+
+  # specify that :id param is a number and cannot be missing or blank
+  param :id, type: :number, allow_blank: false
+  def show
+    # ... your code ...
+  end
+
+  param :id, type: :number, allow_blank: false
+  # Sometimes you may want to specify a scope for the parameters, because you might have
+  # nested params, like `params[:user][:name]`
+  scope :user do
+    param :name, type: :string, allow_blank: false
+    # For string params you can set a format regexp validation, which will be automatically applied
+    param :email, type: :string, required: true, format: URI::MailTo::EMAIL_REGEXP,
+                  modifier: ->(v) { v.strip.downcase }
+    param :birth_date, type: :date, required: true, max: DateTime.now
+  end
+  # You can also specify the scope inline
+  param :preferences, scope: :user, type: :object, default: {}, allow_blank: false
+  def update
+    # ... your code ...
+  end
+end
+```
+
+### Available param types
+
+`Pastore::Params` supports the following param types:
+
+| Param type | Aliases | Description |
+|------------|---------|-------------|
+| `:string`   |         | Accepts string values or converts other value types to string. |
+| `:number`   | `integer`, `float` | Accepts integer values or tries to convert string to number. |
+| `:boolean`  |         | Accepts boolean values or tries to convert string to boolean. |
+| `:date`     |         | Accepts date values or tries to convert string or number (unix time) to date. |
+| `:object`   |         | Accepts object (`Hash`) values or tries to convert JSON string to object. |
+| `:any`      |         | Accepts any value. |
+
+### Avaliable options
+
+There're several generic options that can be used with all param types, which are listed below:
+
+| Option | Value type | Default | Description |
+|--------|------------|---------|-------------|
+| `:type` | `symbol`, `string`, `Class` | `:any` | Specifies the type of the parameter. |
+| `:scope` | `symbol`, `string`, `symbol[]`, `string[]` | `nil` | Specifies the scope of the parameter, which is necessary for nested params definition like `params[:user][:email]`. |
+| `:required` | `boolean` | `false` | When `true`, requires the parameter to be passed by client. |
+| `:allow_blank` | `boolean` | `true` | When `false`, expects parameter's value not to be `nil` or empty. |
+| `:default` | Depends on param type | `nil` | Allows to specify default value to set on parameter when parameter have not been sent by client. |
+| `:modifier` | Lambda block | `nil` | Allows to specify a modifier lambda block, which will be used to modify parameter value. |
+||
+| **String** |
+| `format` | `RegExp` | `nil` | Allows to use a custom `RegExp` to validate parameter value. |
+||
+| **Number** |
+| `min` | `integer`, `float` | `nil` | Allows to specify a minimum value for the parameter. |
+| `max` | `integer`, `float` | `nil` | Allows to specify a maximum value for the parameter. |
+| `clamp` | `Range`, `integer[2]`, `float[2]` | `[-Float::INFINITY, Float::INFINITY]` | Allows to specify a lower and upper bound for the param value, so that a value outside the bounds will be forced to the nearest bound value. |
+||
+| **Date** |
+| `min` | `Date`, `DateTime`, `Time`, `Integer`, `Float` | `nil` | Allows to specify a minimum value for the parameter. |
+| `max` | `Date`, `DateTime`, `Time`, `Integer`, `Float` | `nil` | Allows to specify a maximum value for the parameter. |
+| `clamp` | `Range`, `Date[2]`, `DateTime[2]`, `Time[2]`, `Integer[2]`, `Float[2]` | `nil` | Allows to specify a lower and upper bound for the param value, so that a value outside the bounds will be forced to the nearest bound value. |

data/lib/pastore/guards.rb

@@ -24,6 +24,10 @@ module Pastore
       end
     end
 
+    def current_role
+      self.class.pastore_guards.current_role(self)
+    end
+
     class_methods do # rubocop:disable Metrics/BlockLength
       attr_accessor :_pastore_guards
 

data/lib/pastore/params/action_param.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Pastore
+  module Params
+    # Stores data about action parameters
+    class ActionParam
+      AVAILABLE_TYPES = %w[string number boolean date object array any].freeze
+      TYPE_ALIASES = {
+        'text' => 'string',
+        'integer' => 'number',
+        'float' => 'number',
+        'hash' => 'object'
+      }.freeze
+
+      attr_reader :name, :type, :modifier, :options, :scope
+
+      def initialize(name, **options)
+        @name = name
+        @options = options
+        @scope = [@options&.fetch(:scope, nil)].flatten.compact
+        @array = @options&.fetch(:array, false) == true
+        @modifier = @options&.fetch(:modifier, nil)
+        @type = @options&.fetch(:type, :any)
+
+        check_options!
+      end
+
+      def validate(value)
+        Pastore::Params::Validation.validate!(name, type, value, modifier, **options)
+      end
+
+      def array?
+        @array
+      end
+
+      def name_with_scope
+        [@scope, name].flatten.compact.join('.')
+      end
+
+      private
+
+      def check_options!
+        check_type!
+        check_modifier!
+        check_required!
+        check_default!
+        check_min_max!
+        check_format!
+        check_clamp!
+      end
+
+      def check_type!
+        @type = @type.to_s.strip.downcase
+
+        @type = TYPE_ALIASES[@type] unless TYPE_ALIASES[@type].nil?
+
+        valid_type = AVAILABLE_TYPES.include?(@type)
+        raise Pastore::Params::InvalidParamTypeError, "Invalid param type: #{@type.inspect}" unless valid_type
+      end
+
+      def check_modifier!
+        return if @modifier.nil? || @modifier.is_a?(Proc)
+
+        raise "Invalid modifier, lambda or Proc expected, got #{@modifier.class}"
+      end
+
+      def check_required!
+        options[:required] = (options[:required] == true)
+      end
+
+      def check_default!
+        return if options[:default].nil?
+
+        validation = Pastore::Params::Validation.validate!(name, type, options[:default], modifier, **options)
+        return if validation.valid?
+
+        raise Pastore::Params::InvalidValueError, "Invalid default value: #{validation.errors.join(",")}"
+      end
+
+      def check_min_max!
+        check_min!
+        check_max!
+
+        return if options[:min].nil? || options[:max].nil?
+
+        raise 'Invalid min-max range' unless options[:min] <= options[:max]
+      end
+
+      def check_min!
+        min = options[:min]
+        return if min.nil?
+
+        raise 'Invalid minimum' unless min.is_a?(Integer) || min.is_a?(Float)
+      end
+
+      def check_max!
+        max = options[:max]
+        return if max.nil?
+
+        raise 'Invalid maximum' unless max.is_a?(Integer) || max.is_a?(Float)
+      end
+
+      def check_format!
+        return if options[:format].nil?
+
+        raise 'Invalid format' unless options[:format].is_a?(Regexp)
+      end
+
+      def check_clamp!
+        return if options[:clamp].nil?
+
+        check_clamp_type!
+        convert_clamp_to_array!
+        normalize_datetime_clamp!
+        check_clamp_bounds!
+      end
+
+      def check_clamp_type!
+        return if options[:clamp].nil?
+        return if [Array, Range].include?(options[:clamp].class)
+
+        raise Pastore::Params::InvalidValueError, "Invalid clamp value: #{options[:clamp].inspect}"
+      end
+
+      def convert_clamp_to_array!
+        clamp = options[:clamp]
+
+        options[:clamp] = clamp.is_a?(Array) ? [clamp.first, clamp.last] : [clamp.begin, clamp.end]
+      end
+
+      def check_clamp_bounds!
+        clamp = options[:clamp]
+        return if clamp.first.nil? || clamp.last.nil?
+
+        raise Pastore::Params::InvalidValueError, "Invalid clamp range: #{clamp.inspect}" if clamp.first > clamp.last
+      end
+
+      def normalize_datetime_clamp!
+        return unless @type == 'date'
+
+        options[:clamp] = options[:clamp].map do |d|
+          return d if d.nil?
+
+          case d
+          when Date then d
+          when String then DateTime.parse(d.to_s)
+          when Integer, Float then Time.at(d).to_datetime
+          when Time then d.to_datetime
+          else
+            raise Pastore::Params::InvalidValueError, "Invalid clamp value: #{options[:clamp].inspect}"
+          end
+        end
+      rescue Date::Error
+        raise Pastore::Params::InvalidValueError, "Invalid clamp value: #{options[:clamp].inspect}"
+      end
+    end
+  end
+end

data/lib/pastore/params/settings.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative 'action_param'
+require_relative 'validation'
+
+module Pastore
+  module Params
+    # Implements the logic for params settings storage for a controller.
+    class Settings
+      attr_writer :invalid_params_cbk, :response_status
+
+      def initialize(superklass)
+        @super_params = superklass.pastore_params if superklass.respond_to?(:pastore_params)
+        reset!
+      end
+
+      def reset!
+        @actions = {}
+        @invalid_params_cbk = nil
+        @response_status = nil
+
+        reset_buffer!
+        reset_scope!
+      end
+
+      def invalid_params_cbk
+        @invalid_params_cbk || @super_params&.invalid_params_cbk
+      end
+
+      def response_status
+        @response_status || @super_params&.response_status || :unprocessable_entity
+      end
+
+      def reset_buffer!
+        @buffer = []
+      end
+
+      def set_scope(*keys)
+        @scope = [keys].flatten.compact.map(&:to_sym)
+      end
+
+      def reset_scope!
+        @scope = nil
+      end
+
+      def add(name, **options)
+        options = { scope: @scope }.merge(options.symbolize_keys)
+
+        raise ParamAlreadyDefinedError, "Param #{name} already defined" if @buffer.any? { |p| p.name == name }
+
+        if @scope.present? && options[:scope].present? && @scope != options[:scope]
+          error = "Scope overwrite attempt detected (current_scope: #{@scope}, param_scope: #{options[:scope]}) for param #{name}"
+          raise ScopeConflictError, error
+        end
+
+        param = ActionParam.new(name, **options)
+
+        @buffer << param
+      end
+
+      def save_for(action_name)
+        @actions[action_name.to_sym] = @buffer
+        reset_buffer!
+      end
+
+      def validate(params, action_name)
+        action_params = @actions[action_name.to_sym]
+        return {} if action_params.blank?
+
+        action_params.each_with_object({}) do |validator, errors|
+          value = safe_dig(params, *validator.scope, validator.name)
+          validation = validator.validate(value)
+
+          if validation.valid?
+            update_param_value!(params, validator, validation)
+
+            next if validation.errors.empty?
+          end
+
+          errors[validator.name_with_scope] = validation.errors
+        end
+      end
+
+      private
+
+      def update_param_value!(params, validator, validation)
+        if validator.scope.empty?
+          params[validator.name] = validation.value
+          return
+        end
+
+        # Try to create missing scope keys
+        key_path = []
+        validator.scope.each do |key|
+          params[key] ||= {}
+          key_path << key
+
+          if params[key].is_a?(ActionController::Parameters)
+            params = params[key]
+            next
+          end
+
+          # if for some reason the scope key is not a hash, we need to add the error to validation errors
+          return validation.add_error(:bad_schema, "Invalid param schema at #{key_path.join(".").inspect}")
+        end
+
+        params[validator.name] = validation.value
+      end
+
+      def safe_dig(params, *keys)
+        [keys].flatten.reduce(params) do |acc, key|
+          acc.respond_to?(:key?) ? acc[key] : nil
+        end
+      end
+    end
+  end
+end

data/lib/pastore/params/validation.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Pastore
+  module Params
+    # Implements the logic of a single param validation
+    class Validation
+      require_relative 'validations/string_validation'
+      require_relative 'validations/number_validation'
+      require_relative 'validations/boolean_validation'
+      require_relative 'validations/object_validation'
+      require_relative 'validations/date_validation'
+
+      # Validates the value based on the given type and values with the appropriate validator.
+      def self.validate!(name, type, value, modifier = nil, **options)
+        case type
+        when 'string'  then Pastore::Params::StringValidation.new(name, value, modifier, **options)
+        when 'number'  then Pastore::Params::NumberValidation.new(name, value, modifier, **options)
+        when 'boolean' then Pastore::Params::BooleanValidation.new(name, value, modifier, **options)
+        when 'object'  then Pastore::Params::ObjectValidation.new(name, value, modifier, **options)
+        when 'date'    then Pastore::Params::DateValidation.new(name, value, modifier, **options)
+        when 'any'     then Validation.new(name, 'any', value, modifier, **options)
+        else
+          raise Pastore::Params::InvalidValidationTypeError, "Invalid validation type: #{type}"
+        end
+      end
+
+      attr_reader :value, :errors
+
+      def initialize(name, type, value, modifier = nil, **options)
+        @name = name
+        @type         = type
+        @modifier     = modifier
+        @value        = value.nil? ? options[:default] : value
+        @required     = (options[:required] == true)                           # default: false
+        @allow_blank  = (options[:allow_blank].nil? || options[:allow_blank])  # default: true
+        @allowed_values = options[:in]
+        @exclude_values = options[:exclude]
+
+        @errors = []
+
+        validate!
+      end
+
+      # Returns true if the value is valid, false otherwise.
+      def valid?
+        @errors.empty?
+      end
+
+      # Returns true if the value is required, false otherwise.
+      def required?
+        @required
+      end
+
+      # Adds an error to the list of errors.
+      def add_error(error_type, message)
+        @errors << { type: 'param', name: @name, value: @value, error: error_type, message: message }
+      end
+
+      private
+
+      # Performs a basic validation of the value and applies the modifier.
+      def validate!
+        # check for value presence and if it's allowed to be blank
+        check_presence!
+        apply_modifier!
+      end
+
+      # Checks if the value is present (not nil) and if it's allowed to be blank.
+      def check_presence!
+        valid = true
+
+        # required options ensures that value is present (not nil)
+        valid = false if required? && value.nil?
+
+        # allow_blank option ensures that value is not blank (not empty)
+        valid = false if !@allow_blank && value.to_s.strip == ''
+
+        add_error(:is_blank, "#{@name} cannot be blank") unless valid
+
+        valid
+      end
+
+      # Applies the modifier to the value.
+      def apply_modifier!
+        return if @modifier.nil?
+
+        @value = @modifier.call(@value)
+      end
+
+      # check if value is in the list of allowed values
+      def check_allowed_values!
+        check_inclusion!
+        check_exclusion!
+      end
+
+      def check_inclusion!
+        return if @allowed_values.nil?
+        return if @allowed_values.include?(value)
+
+        add_error(:not_allowed, "#{@name} has invalid value: #{value}")
+      end
+
+      def check_exclusion!
+        return if @exclude_values.nil?
+        return unless @exclude_values.include?(value)
+
+        add_error(:not_allowed, "#{@name} has invalid value: #{value}")
+      end
+
+      # check if value is a number
+      def numeric?
+        !Float(value).nil?
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/pastore/params/validations/boolean_validation.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Pastore
+  module Params
+    # Implements the validation logic for object parameters.
+    class BooleanValidation < Validation
+      def initialize(name, value, modifier, **options)
+        super(name, 'boolean', value, modifier, **options)
+      end
+
+      private
+
+      def validate!
+        # check for value presence and if it's allowed to be blank
+        check_presence!
+
+        # don't go further if value is blank
+        return if value.to_s.strip == ''
+
+        # check if value is a boolean
+        return unless check_if_boolean!
+
+        # check if value is in the list of allowed values
+        check_allowed_values!
+
+        # apply the modifier
+        apply_modifier!
+      end
+
+      def check_if_boolean!
+        return true if [true, false].any?(value)
+
+        if value.is_a?(String) && boolean?
+          @value = %w[t true y yes].any?(value.strip.downcase)
+          return true
+        end
+
+        add_error(:invalid_type, "#{@name} has invalid type: #{@type} expected")
+
+        false
+      end
+
+      def boolean?
+        %w[t true y yes f false n no].any?(value.strip.downcase)
+      end
+    end
+  end
+end

data/lib/pastore/params/validations/date_validation.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Pastore
+  module Params
+    # Implements the validation logic for date parameters.
+    class DateValidation < Validation
+      def initialize(name, value, modifier, **options)
+        @min = options[:min]
+        @max = options[:max]
+        @clamp = options[:clamp]
+
+        super(name, 'date', value, modifier, **options)
+      end
+
+      private
+
+      def validate!
+        # check for value presence and if it's allowed to be blank
+        check_presence!
+
+        # don't go further if value is blank
+        return if value.to_s.strip == ''
+
+        # check if value is a boolean
+        return unless check_if_date! && check_min_max! && check_clamp!
+
+        # check if value is in the list of allowed values
+        check_allowed_values!
+
+        # apply the modifier
+        apply_modifier!
+      end
+
+      def check_if_date!
+        return true if [Date, Time, DateTime].include?(value.class)
+
+        if numeric?
+          @value = Time.at(value.to_f).to_datetime
+          return true
+        end
+
+        # When value is a string, try to parse it as a DateTime object
+        if value.is_a?(String)
+          begin
+            @value = DateTime.parse(value)
+            return true
+          rescue Date::Error
+            # Do nothing
+          end
+        end
+
+        add_error(:invalid_type, "#{@name} has invalid type: #{@type} expected")
+
+        false
+      end
+
+      def check_min_max!
+        min_invalid = @min && value < @min
+        max_invalid = @max && value > @max
+
+        add_error(:too_small, "#{@name} should be greater than #{@min}") if min_invalid
+        add_error(:too_large, "#{@name} should be smaller than #{@max}") if max_invalid
+
+        min_invalid || max_invalid ? false : true
+      end
+
+      def check_clamp!
+        return true if @clamp.nil?
+
+        @value = @value.clamp(@clamp.first, @clamp.last)
+      end
+    end
+  end
+end