interactor-validation 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a2389fc324f275ef082e2d5b24174f8c753c88a5adc3d4ed6499670b6a1da11
-  data.tar.gz: dc45f25929ca97a2a49dc4663e885dff8780d1dc54d4d11bb8555e39fd00c11f
+  metadata.gz: b8c04f34a47f6d887079d08a07958d91c19932a1b3c190faaa0ba4f1a85dbbf2
+  data.tar.gz: 167cbca80c87fe0519f3bab2a1e36c4d753366126e5587d3559907473d558812
 SHA512:
-  metadata.gz: dfc83bceb6887d5b45338a0801ba61e9e978bbbd319fa5b43d754bc50cc18f863fda7d841e1dd8a749292bc9ffb998bb476df57b0e76091075723fc157281d2f
-  data.tar.gz: f0ab78c0e9f364da7c343fd5799d020c8dd4e3139c7b859c95ae8f7d10470c24a6b1e519516b27b0eff06627549075bb8b1d1e125afde15f2cea2b88e91459d3
+  metadata.gz: 03a955748e4429b6e141a17292484ec49bf52c5a8af056c7436270f91a9a536c1e782a6ca7d3af38b4437736dd960491735eb233c4abe3599d96a604d9297966
+  data.tar.gz: 0ba87d4e8591ff0ba7cb260d10bda55c8d0526bb8de75cc66a7c81b0addf2d5355d4f9da9919e3ad76fe3052e43868d7af39eb5d57729319ed92500ad12c5e61

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 ## [Unreleased]
 
+## [0.2.0] - 2024-11-16
+
+### Security
+
+- **CRITICAL:** Added ReDoS (Regular Expression Denial of Service) protection with configurable timeout
+- **HIGH:** Fixed thread safety issues in validation rule registration using mutex locks
+- Added memory protection with configurable maximum array size for nested validations
+- Added regex pattern caching to prevent recompilation attacks
+
+### Bug Fixes
+
+- Fixed numeric precision loss bug - now uses `to_i` for integers and `to_f` for floats
+- Fixed ambiguous handling of `nil` vs missing hash keys in nested validation
+- Improved boolean validation to properly distinguish between `nil`, `false`, and missing values
+
+### Performance Improvements
+
+- Implemented regex pattern caching for up to 10x performance improvement on repeated validations
+- Added configuration memoization during validation to reduce overhead
+- Optimized string-to-numeric coercion to preserve integer precision
+
+### New Features
+
+- Added `config.regex_timeout` - Configurable timeout for regex validation (default: 100ms)
+- Added `config.max_array_size` - Maximum array size for nested validation (default: 1000)
+- Added `config.enable_instrumentation` - ActiveSupport::Notifications integration for monitoring
+- Added `config.cache_regex_patterns` - Enable/disable regex pattern caching (default: true)
+- Created `ErrorCodes` module with constants for all error types
+- Added comprehensive YARD documentation for public API methods
+
+### Documentation
+
+- Added SECURITY.md with vulnerability reporting process and security best practices
+- Added benchmark suite in `benchmark/validation_benchmark.rb`
+- Enhanced inline documentation with YARD tags for all public methods
+- Improved code organization by extracting error codes into separate module
+
+### Breaking Changes
+
+None - this release is fully backward compatible with 0.1.x
+
+### Upgrade Notes
+
+To take advantage of the new security features, no changes are required. However, you may want to configure:
+
+```ruby
+Interactor::Validation.configure do |config|
+  config.regex_timeout = 0.05        # Stricter timeout for high-security contexts
+  config.max_array_size = 100        # Lower limit for your use case
+  config.enable_instrumentation = true # Monitor validation performance
+end
+```
+
+## [0.1.1] - 2025-11-16
+
+- Minor version bump for release preparation
+
 ## [0.1.0] - 2025-11-16
 
 - Initial release

data/README.md

@@ -1,6 +1,6 @@
 # Interactor::Validation
 
-Add Rails-style parameter validation to your [Interactor](https://github.com/collectiveidea/interactor) service objects with simple, declarative syntax.
+Add declarative parameter validation to your [Interactor](https://github.com/collectiveidea/interactor) service objects with Rails-style syntax.
 
 ## Installation
 
@@ -27,124 +27,165 @@ class CreateUser
   end
 end
 
-# Success
-result = CreateUser.call(email: "dev@example.com", username: "developer", age: 25)
-result.success? # => true
-result.user     # => #<User...>
-
-# Failure - automatic validation
+# Validation runs automatically before call
 result = CreateUser.call(email: "", username: "ab", age: -5)
 result.failure? # => true
 result.errors   # => [
-                #      { code: "EMAIL_IS_REQUIRED" },
-                #      { code: "USERNAME_BELOW_MIN_LENGTH_3" },
-                #      { code: "AGE_MUST_BE_GREATER_THAN_0" }
+                #      { attribute: :email, type: :blank, message: "Email can't be blank" },
+                #      { attribute: :username, type: :too_short, message: "Username is too short (minimum is 3 characters)" },
+                #      { attribute: :age, type: :greater_than, message: "Age must be greater than 0" }
                 #    ]
 ```
 
-## Features
-
-### Parameter Declaration
+## Validation Types
 
-Use `params` to declare expected parameters - they're automatically delegated to context:
+### Presence
 
-```ruby
-params :user_id, :action
-
-def call
-  # Access directly instead of context.user_id
-  user = User.find(user_id)
-  user.perform(action)
-end
-```
-
-### Validation Rules
-
-All validations run **before** your `call` method. If validation fails, the interactor stops and returns structured errors.
-
-**Presence**
 ```ruby
 validates :name, presence: true
-# Error: { code: "NAME_IS_REQUIRED" }
+# Error: { attribute: :name, type: :blank, message: "Name can't be blank" }
 ```
 
-**Format (Regex)**
+### Format (Regex)
+
 ```ruby
 validates :email, format: { with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i }
-# Error: { code: "EMAIL_INVALID_FORMAT" }
+# Error: { attribute: :email, type: :invalid, message: "Email is invalid" }
 ```
 
-**Length**
+### Length
+
 ```ruby
 validates :password, length: { minimum: 8, maximum: 128 }
 validates :code, length: { is: 6 }
-# Errors: { code: "PASSWORD_BELOW_MIN_LENGTH_8" }
-#         { code: "CODE_INVALID_LENGTH_6" }
+# Errors: { attribute: :password, type: :too_short, message: "Password is too short (minimum is 8 characters)" }
+#         { attribute: :code, type: :wrong_length, message: "Code is the wrong length (should be 6 characters)" }
 ```
 
-**Inclusion**
+### Inclusion
+
 ```ruby
 validates :status, inclusion: { in: %w[active pending inactive] }
-# Error: { code: "STATUS_NOT_IN_LIST" }
+# Error: { attribute: :status, type: :inclusion, message: "Status is not included in the list" }
 ```
 
-**Numericality**
+### Numericality
+
 ```ruby
 validates :price, numericality: { greater_than_or_equal_to: 0 }
 validates :quantity, numericality: { greater_than: 0, less_than_or_equal_to: 100 }
-# Errors: { code: "PRICE_MUST_BE_GREATER_THAN_OR_EQUAL_TO_0" }
+validates :count, numericality: true  # Just check if numeric
+
+# Available constraints:
+# - greater_than, greater_than_or_equal_to
+# - less_than, less_than_or_equal_to
+# - equal_to
+```
+
+### Boolean
+
+```ruby
+validates :is_active, boolean: true
+# Ensures value is true or false (not truthy/falsy)
+```
+
+### Nested Validation
+
+Validate nested hashes and arrays:
+
+```ruby
+# Hash validation
+params :user
+validates :user do
+  attribute :name, presence: true
+  attribute :email, format: { with: /@/ }
+  attribute :age, numericality: { greater_than: 0 }
+end
+
+# Array validation
+params :items
+validates :items do
+  attribute :name, presence: true
+  attribute :price, numericality: { greater_than: 0 }
+end
 ```
 
-### Error Formats
+## Error Formats
 
-The gem supports two error formatting modes:
+Choose between two error format modes:
 
-#### Code Mode (Default)
+### Default Mode (ActiveModel-style)
 
-Returns structured error codes ideal for APIs and i18n:
+Human-readable errors with full context - ideal for forms and user-facing applications:
 
 ```ruby
+# This is the default, no configuration needed
 result.errors # => [
-              #      { code: "EMAIL_IS_REQUIRED" },
-              #      { code: "USERNAME_BELOW_MIN_LENGTH_3" }
+              #      { attribute: :email, type: :blank, message: "Email can't be blank" },
+              #      { attribute: :username, type: :too_short, message: "Username is too short" }
               #    ]
 ```
 
-#### Default Mode
+### Code Mode
 
-Returns ActiveModel-style errors with human-readable messages:
+Structured error codes - ideal for APIs and internationalization:
 
 ```ruby
-Interactor::Validation.configure do |config|
-  config.error_mode = :default
+configure_validation do |config|
+  config.error_mode = :code
 end
 
 result.errors # => [
-              #      { attribute: :email, type: :blank, message: "Email can't be blank" },
-              #      { attribute: :username, type: :too_short, message: "Username is too short (minimum is 3 characters)" }
+              #      { code: "EMAIL_IS_REQUIRED" },
+              #      { code: "USERNAME_BELOW_MIN_LENGTH_3" }
               #    ]
 ```
 
+### Custom Messages
+
+Provide custom error messages for any validation:
+
+```ruby
+# Works with both modes
+validates :username, presence: { message: "Username is required" }
+validates :email, format: { with: /@/, message: "Invalid email format" }
+
+# In :code mode, custom messages become part of the code
+configure_validation { |c| c.error_mode = :code }
+validates :age, numericality: { greater_than: 0, message: "INVALID_AGE" }
+# => { code: "AGE_INVALID_AGE" }
+```
+
 ## Configuration
 
 ### Global Configuration
 
-Configure validation behavior for all interactors:
+Configure behavior for all interactors:
 
 ```ruby
 # config/initializers/interactor_validation.rb
 Interactor::Validation.configure do |config|
-  # Error format mode: :code (default) or :default
-  config.error_mode = :code
+  # Error format: :default (ActiveModel-style) or :code (structured codes)
+  config.error_mode = :default
 
-  # Stop validation at first error (default: false)
+  # Stop at first error for better performance
   config.halt_on_first_error = false
+
+  # Security settings
+  config.regex_timeout = 0.1        # Regex timeout in seconds (ReDoS protection)
+  config.max_array_size = 1000      # Max array size for nested validation
+
+  # Performance settings
+  config.cache_regex_patterns = true
+
+  # Monitoring
+  config.enable_instrumentation = false
 end
 ```
 
 ### Per-Interactor Configuration
 
-Override global settings for specific interactors:
+Override settings for specific interactors:
 
 ```ruby
 class CreateUser
@@ -152,7 +193,7 @@ class CreateUser
   include Interactor::Validation
 
   configure_validation do |config|
-    config.error_mode = :default
+    config.error_mode = :code
     config.halt_on_first_error = true
   end
 
@@ -161,47 +202,37 @@ class CreateUser
 end
 ```
 
-### Custom Error Messages
+## Advanced Features
 
-Provide custom error messages for any validation:
+### Parameter Declaration
 
-```ruby
-# With :code mode
-configure_validation do |config|
-  config.error_mode = :code
-end
+Declare parameters for automatic delegation to context:
 
-validates :username, presence: { message: "CUSTOM_REQUIRED_ERROR" }
-validates :email, format: { with: /@/, message: "CUSTOM_FORMAT_ERROR" }
-# => { code: "USERNAME_CUSTOM_REQUIRED_ERROR" }
-# => { code: "EMAIL_CUSTOM_FORMAT_ERROR" }
+```ruby
+params :user_id, :action
 
-# With :default mode
-configure_validation do |config|
-  config.error_mode = :default
+def call
+  # Access directly instead of context.user_id
+  user = User.find(user_id)
+  user.perform(action)
 end
-
-validates :bio, length: { maximum: 500, message: "is too long (max 500 chars)" }
-# => { attribute: :bio, type: :too_long, message: "is too long (max 500 chars)" }
 ```
 
-### Advanced Usage
-
-#### Halt on First Error
+### Halt on First Error
 
-Improve performance by stopping validation at the first failure:
+Improve performance by stopping validation early:
 
 ```ruby
 configure_validation do |config|
-  config.halt_on_first_error = true  # Stop at first error
+  config.halt_on_first_error = true
 end
 
 validates :field1, presence: true
 validates :field2, presence: true  # Won't run if field1 fails
-validates :field3, presence: true  # Won't run if field1 or field2 fails
+validates :field3, presence: true  # Won't run if earlier fields fail
 ```
 
-#### Integration with ActiveModel Validations
+### ActiveModel Integration
 
 Use ActiveModel's custom validation callbacks:
 
@@ -212,30 +243,90 @@ class CreateUser
 
   params :user_data
 
-  validate :check_user_data_structure
+  validate :check_custom_logic
   validates :username, presence: true
 
-  def check_user_data_structure
-    errors.add(:user_data, "must be a Hash") unless user_data.is_a?(Hash)
+  private
+
+  def check_custom_logic
+    errors.add(:base, "Custom validation failed") unless custom_condition?
   end
 end
 ```
 
+### Performance Monitoring
+
+Track validation performance in production:
+
+```ruby
+config.enable_instrumentation = true
+
+ActiveSupport::Notifications.subscribe('validate_params.interactor_validation') do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Rails.logger.info "Validation: #{event.duration}ms (#{event.payload[:interactor]})"
+end
+```
+
+## Security
+
+Built-in protection against common vulnerabilities:
+
+### ReDoS Protection
+
+Automatic timeouts prevent Regular Expression Denial of Service attacks:
+
+```ruby
+config.regex_timeout = 0.1  # 100ms default
+```
+
+If a regex exceeds the timeout, validation fails safely instead of hanging.
+
+### Memory Protection
+
+Array size limits prevent memory exhaustion:
+
+```ruby
+config.max_array_size = 1000  # Default limit
+```
+
+### Thread Safety
+
+All validation operations are thread-safe for use with Puma, Sidekiq, etc.
+
+### Best Practices
+
+- Use simple regex patterns (avoid nested quantifiers)
+- Sanitize error messages before displaying in HTML
+- Set appropriate `max_array_size` limits for your use case
+- Enable instrumentation to monitor performance
+- Review [SECURITY.md](SECURITY.md) for detailed information
+
 ## Development
 
 ```bash
 bin/setup              # Install dependencies
-bundle exec rspec      # Run tests
+bundle exec rspec      # Run tests (231 examples)
 bundle exec rubocop    # Lint code
 bin/console            # Interactive console
 ```
 
+### Benchmarking
+
+```bash
+bundle exec ruby benchmark/validation_benchmark.rb
+```
+
 ## Requirements
 
 - Ruby >= 3.2.0
 - Interactor ~> 3.0
 - ActiveModel >= 6.0
+- ActiveSupport >= 6.0
 
 ## License
 
 MIT License - see [LICENSE.txt](LICENSE.txt)
+
+## Contributing
+
+Issues and pull requests are welcome at [https://github.com/zyxzen/interactor-validation](https://github.com/zyxzen/interactor-validation)

data/benchmark/validation_benchmark.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "benchmark/ips"
+require "interactor"
+require "interactor/validation"
+
+# Benchmark different validation scenarios
+puts "Interactor::Validation Performance Benchmarks"
+puts "=" * 60
+
+# Setup test interactors
+class SimplePresenceInteractor
+  include Interactor
+  include Interactor::Validation
+
+  params :username, :email
+
+  validates :username, presence: true
+  validates :email, presence: true
+
+  def call; end
+end
+
+class ComplexValidationInteractor
+  include Interactor
+  include Interactor::Validation
+
+  params :username, :email, :age, :bio
+
+  validates :username, presence: true, length: { minimum: 3, maximum: 20 }
+  validates :email, presence: true, format: { with: /\A[\w+\-.]+@[a-z\d-]+(\.[a-z\d-]+)*\.[a-z]+\z/i }
+  validates :age, numericality: { greater_than: 0, less_than: 150 }
+  validates :bio, length: { maximum: 500 }
+
+  def call; end
+end
+
+class NestedValidationInteractor
+  include Interactor
+  include Interactor::Validation
+
+  params :user_data
+
+  validates :user_data do |v|
+    v.attribute :name, presence: true, length: { minimum: 2 }
+    v.attribute :email, presence: true, format: { with: /\A[\w+\-.]+@[a-z\d-]+(\.[a-z\d-]+)*\.[a-z]+\z/i }
+    v.attribute :age, numericality: { greater_than: 0 }
+  end
+
+  def call; end
+end
+
+class ArrayValidationInteractor
+  include Interactor
+  include Interactor::Validation
+
+  params :items
+
+  validates :items do |v|
+    v.attribute :name, presence: true
+    v.attribute :price, numericality: { greater_than: 0 }
+  end
+
+  def call; end
+end
+
+# Valid test data
+valid_simple_data = { username: "john_doe", email: "john@example.com" }
+valid_complex_data = {
+  username: "john_doe",
+  email: "john@example.com",
+  age: 25,
+  bio: "Software developer"
+}
+valid_nested_data = {
+  user_data: {
+    name: "John Doe",
+    email: "john@example.com",
+    age: 25
+  }
+}
+valid_array_data = {
+  items: [
+    { name: "Item 1", price: 10.99 },
+    { name: "Item 2", price: 20.50 },
+    { name: "Item 3", price: 15.75 }
+  ]
+}
+
+# Invalid test data
+invalid_simple_data = { username: "", email: "" }
+
+# Benchmark: Simple presence validation
+puts "\n1. Simple Presence Validation (2 fields)"
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("valid data") do
+    SimplePresenceInteractor.call(valid_simple_data)
+  end
+
+  x.report("invalid data") do
+    result = SimplePresenceInteractor.call(invalid_simple_data)
+    result.failure?
+  end
+
+  x.compare!
+end
+
+# Benchmark: Complex multi-rule validation
+puts "\n2. Complex Validation (4 fields, multiple rules)"
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("valid data") do
+    ComplexValidationInteractor.call(valid_complex_data)
+  end
+
+  x.compare!
+end
+
+# Benchmark: Nested validation
+puts "\n3. Nested Hash Validation"
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("valid nested data") do
+    NestedValidationInteractor.call(valid_nested_data)
+  end
+
+  x.compare!
+end
+
+# Benchmark: Array validation
+puts "\n4. Array Validation (3 items)"
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("valid array") do
+    ArrayValidationInteractor.call(valid_array_data)
+  end
+
+  x.compare!
+end
+
+# Benchmark: Regex caching impact
+puts "\n5. Regex Pattern Caching (100 iterations)"
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("with caching") do
+    Interactor::Validation.configure { |c| c.cache_regex_patterns = true }
+    100.times { ComplexValidationInteractor.call(valid_complex_data) }
+  end
+
+  x.report("without caching") do
+    Interactor::Validation.configure { |c| c.cache_regex_patterns = false }
+    100.times { ComplexValidationInteractor.call(valid_complex_data) }
+  end
+
+  x.compare!
+end
+
+# Benchmark: Halt on first error
+puts "\n6. Halt on First Error (invalid data, 4 fields)"
+invalid_all_data = { username: "", email: "invalid", age: -1, bio: "a" * 600 }
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("halt enabled") do
+    Interactor::Validation.configure { |c| c.halt_on_first_error = true }
+    ComplexValidationInteractor.call(invalid_all_data)
+  end
+
+  x.report("halt disabled") do
+    Interactor::Validation.configure { |c| c.halt_on_first_error = false }
+    ComplexValidationInteractor.call(invalid_all_data)
+  end
+
+  x.compare!
+end
+
+# Benchmark: Error mode comparison
+puts "\n7. Error Formatting Mode"
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("code mode") do
+    Interactor::Validation.configure { |c| c.error_mode = :code }
+    SimplePresenceInteractor.call(invalid_simple_data)
+  end
+
+  x.report("default mode") do
+    Interactor::Validation.configure { |c| c.error_mode = :default }
+    SimplePresenceInteractor.call(invalid_simple_data)
+  end
+
+  x.compare!
+end
+
+# Benchmark: Large array validation
+puts "\n8. Large Array Validation (100 items)"
+large_array_data = {
+  items: Array.new(100) { |i| { name: "Item #{i}", price: rand(1.0..100.0).round(2) } }
+}
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("100 items") do
+    ArrayValidationInteractor.call(large_array_data)
+  end
+
+  x.compare!
+end
+
+# Reset configuration
+Interactor::Validation.reset_configuration!
+
+puts "\n#{"=" * 60}"
+puts "Benchmarks complete!"
+puts "\nTo run these benchmarks:"
+puts "  bundle exec ruby benchmark/validation_benchmark.rb"
+puts "\nTo add benchmark-ips to your Gemfile:"
+puts "  gem 'benchmark-ips', '~> 2.0', group: :development"