reactive-actions 0.1.0.pre.alpha.1 → 0.1.0.pre.alpha.3

data/lib/generators/reactive_actions/install/templates/README

@@ -2,31 +2,107 @@
 
 ReactiveActions has been installed successfully!
 
-Routes have been added to your config/routes.rb file:
+SETUP COMPLETED:
+================
+
+✓ Routes added to config/routes.rb:
   mount ReactiveActions::Engine, at: '/reactive_actions'
 
-You can now access the reactive actions functionality at:
-  http://localhost:3000/reactive_actions/execute
+✓ JavaScript client configured with automatic initialization
+  - Added to config/importmap.rb
+  - Initialized in app/javascript/application.js
+  - Available globally as window.ReactiveActions
 
-A sample action has been created at:
+✓ Sample action created:
   app/reactive_actions/example_action.rb
 
-You can try it out with:
-  
-  # Using HTTP
-  curl -X POST http://localhost:3000/reactive_actions/execute \
-    -H "Content-Type: application/json" \
-    -d '{"action_name": "example", "action_params": {"name": "YourName"}}'
-  
-  # Using JavaScript client
-  ReactiveActions.execute('example', { name: 'YourName' })
-    .then(response => console.log(response))
-
-To create your own actions, add more files to the app/reactive_actions directory.
-Each action should inherit from ReactiveActions::ReactiveAction and define
-at least the `action` and `response` methods.
-
-For more information, see the documentation at:
+QUICK START:
+============
+
+1. Test the API endpoint:
+   curl -X POST http://localhost:3000/reactive_actions/execute \
+     -H "Content-Type: application/json" \
+     -d '{"action_name": "example", "action_params": {"name": "YourName"}}'
+
+2. Use JavaScript client:
+   ReactiveActions.execute('example', { name: 'YourName' })
+     .then(response => console.log(response))
+
+3. Use DOM binding (no JavaScript required):
+   <button reactive-action="click->example" 
+           reactive-action-name="YourName">
+     Test Action
+   </button>
+
+JAVASCRIPT CLIENT:
+==================
+
+The ReactiveActions client is automatically initialized and available as:
+- window.ReactiveActions (global)
+- Supports all HTTP methods: get, post, put, patch, delete
+- Automatic CSRF token handling
+- DOM binding with mutation observer
+
+Examples:
+  // Execute actions
+  ReactiveActions.execute('action_name', { param: 'value' })
+  ReactiveActions.post('create_user', { name: 'John' })
+  ReactiveActions.get('fetch_data', { id: 123 })
+
+  // Configuration (if needed)
+  ReactiveActions.configure({
+    baseUrl: '/custom/path/execute',
+    defaultHttpMethod: 'PUT'
+  }).reinitialize()
+
+DOM BINDING:
+============
+
+Add reactive-action attributes to any element:
+
+  <!-- Basic actions -->
+  <button reactive-action="click->update_user">Update</button>
+  <input reactive-action="change->search" type="text">
+  <form reactive-action="submit->create_post">...</form>
+
+  <!-- With HTTP methods -->
+  <button reactive-action="click->put#update_user">Update (PUT)</button>
+  <button reactive-action="click->delete#remove_user">Delete</button>
+
+  <!-- Pass data via attributes -->
+  <button reactive-action="click->update_user"
+          reactive-action-user-id="123"
+          reactive-action-name="John">
+    Update User
+  </button>
+
+CREATING ACTIONS:
+=================
+
+Add files to app/reactive_actions/:
+
+  # app/reactive_actions/update_user_action.rb
+  class UpdateUserAction < ReactiveActions::ReactiveAction
+    def action
+      user = User.find(action_params[:user_id])
+      user.update(name: action_params[:name])
+      @result = { success: true, user: user.as_json }
+    end
+
+    def response
+      render json: @result
+    end
+  end
+
+DOCUMENTATION & SUPPORT:
+========================
+
+For complete documentation and examples:
   https://github.com/IstvanMs/reactive-actions
 
+For troubleshooting and configuration options:
+  Check config/initializers/reactive_actions.rb
+
+Happy coding with ReactiveActions! 🚀
+
 ===============================================================================

data/lib/generators/reactive_actions/install/templates/initializer.rb

@@ -7,7 +7,66 @@ ReactiveActions.configure do |config|
 
   # Configure instance variables to delegate from the controller to action classes
   # config.delegated_instance_variables += [:custom_variable]
+
+  # Rate Limiting Configuration
+  # ============================
+  
+<% if rate_limiting_config[:rate_limiting_enabled] -%>
+  # Rate limiting is enabled
+  config.rate_limiting_enabled = true
+
+<% if rate_limiting_config[:global_rate_limiting_enabled] -%>
+  # Global controller-level rate limiting is enabled
+  config.global_rate_limiting_enabled = true
+  config.global_rate_limit = <%= rate_limiting_config[:global_rate_limit] || 600 %>
+  config.global_rate_limit_window = <%= rate_limiting_config[:global_rate_limit_window] || '1.minute' %>
+
+<% else -%>
+  # Global rate limiting is disabled
+  config.global_rate_limiting_enabled = false
+
+<% end -%>
+<% if rate_limiting_config[:custom_key_generator] -%>
+  # Custom rate limit key generator
+  # Uncomment and customize as needed:
+  # config.rate_limit_key_generator = ->(request, action_name) do
+  #   # Example: user-based key with action scope
+  #   user_id = request.headers['X-User-ID'] || 'anonymous'
+  #   "#{action_name}:user:#{user_id}"
+  # end
+
+<% end -%>
+<% else -%>
+  # Rate limiting is disabled by default
+  # To enable rate limiting, uncomment and configure:
+  # config.rate_limiting_enabled = true
+  # config.global_rate_limiting_enabled = true
+  # config.global_rate_limit = 600
+  # config.global_rate_limit_window = 1.minute
+  
+  # Custom rate limit key generator (optional)
+  # config.rate_limit_key_generator = ->(request, action_name) do
+  #   # Example: user-based key with action scope
+  #   user_id = request.headers['X-User-ID'] || 'anonymous'
+  #   "#{action_name}:user:#{user_id}"
+  # end
+
+<% end -%>
 end
 
 # Set the logger for ReactiveActions
 ReactiveActions.logger = Rails.logger
+
+# JavaScript Client Configuration
+# ================================
+# The JavaScript client is automatically initialized in application.js
+# You can reconfigure it at runtime if needed:
+#
+# ReactiveActions.configure({
+#   baseUrl: '/custom/path/execute',
+#   enableAutoBinding: true,
+#   enableMutationObserver: true,
+#   defaultHttpMethod: 'POST'
+# }).reinitialize();
+#
+# Available globally as window.ReactiveActions

data/lib/reactive_actions/concerns/rate_limiter.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module ReactiveActions
+  module Concerns
+    # Rate limiting module for ReactiveActions that can be included in actions or other classes
+    # Provides convenient methods for checking and managing rate limits
+    module RateLimiter
+      # Helper method for rate limiting in security checks or actions
+      # Automatically respects the global rate_limiting_enabled setting
+      # @param key [String, nil] Custom cache key, uses default if nil
+      # @param limit [Integer] Maximum number of requests allowed
+      # @param window [ActiveSupport::Duration] Time window for the limit
+      # @param cost [Integer] Cost of this request (default: 1)
+      # @raise [RateLimitExceededError] When rate limit is exceeded
+      def rate_limit!(key: nil, limit: 100, window: 1.hour, cost: 1)
+        # Early return if rate limiting is disabled
+        return unless ReactiveActions.configuration.rate_limiting_enabled
+
+        effective_key = key || default_rate_limit_key
+
+        ReactiveActions::RateLimiter.check!(
+          key: effective_key,
+          limit: limit,
+          window: window,
+          cost: cost
+        )
+      end
+
+      # Check rate limit without raising an error (also respects configuration)
+      # @param key [String, nil] Custom cache key, uses default if nil
+      # @param limit [Integer] Maximum number of requests allowed
+      # @param window [ActiveSupport::Duration] Time window for the limit
+      # @return [Hash] Rate limit status information
+      def rate_limit_status(key: nil, limit: 100, window: 1.hour)
+        # Return "unlimited" status if rate limiting is disabled
+        unless ReactiveActions.configuration.rate_limiting_enabled
+          return {
+            limit: Float::INFINITY,
+            remaining: Float::INFINITY,
+            current: 0,
+            window: window,
+            exceeded: false,
+            enabled: false
+          }
+        end
+
+        effective_key = key || default_rate_limit_key
+
+        ReactiveActions::RateLimiter.check(
+          key: effective_key,
+          limit: limit,
+          window: window
+        ).merge(enabled: true)
+      end
+
+      # Reset rate limit for a specific key
+      # @param key [String, nil] Custom cache key, uses default if nil
+      # @param window [ActiveSupport::Duration] Time window for the limit
+      def reset_rate_limit!(key: nil, window: 1.hour)
+        return unless ReactiveActions.configuration.rate_limiting_enabled
+
+        effective_key = key || default_rate_limit_key
+
+        ReactiveActions::RateLimiter.reset!(
+          key: effective_key,
+          window: window
+        )
+      end
+
+      # Check if rate limiting is currently enabled
+      # @return [Boolean] True if rate limiting is enabled
+      def rate_limiting_enabled?
+        ReactiveActions.configuration.rate_limiting_enabled
+      end
+
+      # Get remaining requests for a specific key without consuming any
+      # @param key [String, nil] Custom cache key, uses default if nil
+      # @param limit [Integer] Maximum number of requests allowed
+      # @param window [ActiveSupport::Duration] Time window for the limit
+      # @return [Integer, Float] Number of remaining requests, or Float::INFINITY if disabled
+      def rate_limit_remaining(key: nil, limit: 100, window: 1.hour)
+        status = rate_limit_status(key: key, limit: limit, window: window)
+        status[:remaining]
+      end
+
+      # Check if a key would exceed rate limit for a given cost
+      # @param key [String, nil] Custom cache key, uses default if nil
+      # @param limit [Integer] Maximum number of requests allowed
+      # @param window [ActiveSupport::Duration] Time window for the limit
+      # @param cost [Integer] Cost to check (default: 1)
+      # @return [Boolean] True if the cost would exceed the limit
+      def rate_limit_would_exceed?(key: nil, limit: 100, window: 1.hour, cost: 1)
+        return false unless ReactiveActions.configuration.rate_limiting_enabled
+
+        status = rate_limit_status(key: key, limit: limit, window: window)
+        status[:remaining] < cost
+      end
+
+      # Create a rate limit key for a specific scope
+      # @param scope [String, Symbol] The scope (e.g., 'api', 'search', 'upload')
+      # @param identifier [String, nil] Custom identifier, uses default if nil
+      # @return [String] Formatted rate limit key
+      def rate_limit_key_for(scope, identifier: nil)
+        base_key = identifier || extract_identifier_from_context
+        "#{scope}:#{base_key}"
+      end
+
+      # Log rate limiting events for debugging/monitoring
+      # @param event [String] Event type (e.g., 'exceeded', 'checked', 'reset')
+      # @param details [Hash] Additional details to log
+      def log_rate_limit_event(event, details = {})
+        return unless ReactiveActions.logger
+
+        ReactiveActions.logger.info(
+          "Rate Limit #{event.capitalize}: #{details.merge(key: default_rate_limit_key)}"
+        )
+      end
+
+      private
+
+      # Default key generation for rate limiting
+      # This method tries different approaches to generate a meaningful key
+      # @return [String] A rate limit key
+      def default_rate_limit_key
+        # Try different methods to get a meaningful identifier
+        if respond_to?(:current_user) && current_user
+          "user:#{current_user.id}"
+        elsif respond_to?(:controller) && controller.respond_to?(:request)
+          extract_key_from_request(controller.request)
+        elsif respond_to?(:request) && request
+          extract_key_from_request(request)
+        else
+          "anonymous:#{SecureRandom.hex(8)}"
+        end
+      end
+
+      # Extract identifier from current context (user, request, etc.)
+      # @return [String] An identifier for the current context
+      def extract_identifier_from_context
+        if respond_to?(:current_user) && current_user
+          current_user.id.to_s
+        elsif respond_to?(:controller) && controller.respond_to?(:request)
+          controller.request.remote_ip
+        elsif respond_to?(:request) && request
+          request.remote_ip
+        else
+          'unknown'
+        end
+      end
+
+      # Extract a rate limiting key from a request object
+      # @param request [ActionDispatch::Request] The request object
+      # @return [String] A rate limit key based on the request
+      def extract_key_from_request(request)
+        # Try to get user info from headers first
+        if request.headers['X-User-ID'].present?
+          "user:#{request.headers['X-User-ID']}"
+        elsif request.headers['Authorization'].present?
+          # Extract from API token/key
+          auth_header = request.headers['Authorization']
+          if auth_header.start_with?('Bearer ')
+            token = auth_header.gsub('Bearer ', '')
+            "token:#{Digest::SHA256.hexdigest(token)[0..8]}" # Hash for privacy
+          else
+            "auth:#{request.remote_ip}"
+          end
+        else
+          # Fallback to IP address
+          "ip:#{request.remote_ip}"
+        end
+      end
+    end
+  end
+end

data/lib/reactive_actions/concerns/security_checks.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module ReactiveActions
+  module Concerns
+    # Security checks module that provides simple security filtering with function names or lambdas
+    module SecurityChecks
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :security_filters, default: []
+      end
+
+      class_methods do
+        # Add a security check that runs before the action
+        #
+        # @param check [Symbol, Proc] The method name or lambda to execute
+        # @param options [Hash] Conditions for when to run the check
+        # @option options [Symbol, Array<Symbol>] :only Run only for these actions
+        # @option options [Symbol, Array<Symbol>] :except Skip for these actions
+        # @option options [Symbol, Proc] :if Run only if condition is true
+        # @option options [Symbol, Proc] :unless Skip if condition is true
+        def security_check(check, **options)
+          self.security_filters = security_filters + [{ check: check, **options }]
+        end
+
+        # Skip all security checks for this action
+        def skip_security_checks
+          self.security_filters = []
+        end
+      end
+
+      private
+
+      # Run all configured security checks
+      def run_security_checks
+        self.class.security_filters.each do |filter_config|
+          next unless should_run_security_check?(filter_config)
+
+          execute_security_check(filter_config[:check])
+        end
+      end
+
+      # Determine if a security check should run based on conditions
+      def should_run_security_check?(filter_config)
+        return false unless check_only_condition(filter_config[:only])
+        return false if check_except_condition(filter_config[:except])
+        return false unless check_if_condition(filter_config[:if])
+        return false if check_unless_condition(filter_config[:unless])
+
+        true
+      end
+
+      def check_only_condition(only_condition)
+        return true unless only_condition
+
+        only_actions = Array(only_condition).map(&:to_s)
+        only_actions.include?('action')
+      end
+
+      def check_except_condition(except_condition)
+        return false unless except_condition
+
+        except_actions = Array(except_condition).map(&:to_s)
+        except_actions.include?('action')
+      end
+
+      def check_if_condition(if_condition)
+        return true unless if_condition
+
+        evaluate_condition(if_condition)
+      end
+
+      def check_unless_condition(unless_condition)
+        return false unless unless_condition
+
+        evaluate_condition(unless_condition)
+      end
+
+      def evaluate_condition(condition)
+        if condition.is_a?(Proc)
+          instance_exec(&condition)
+        elsif condition.is_a?(Symbol)
+          send(condition)
+        else
+          false
+        end
+      end
+
+      # Execute a single security check
+      def execute_security_check(check)
+        if check.is_a?(Proc)
+          instance_exec(&check)
+        elsif check.is_a?(Symbol)
+          send(check)
+        else
+          raise ReactiveActions::SecurityCheckError, "Invalid security check: #{check.inspect}"
+        end
+      rescue ReactiveActions::Error
+        # Re-raise ReactiveActions errors as-is
+        raise
+      rescue StandardError => e
+        # Convert other errors to security errors
+        ReactiveActions.logger.error "Security check failed in #{self.class.name}: #{e.message}"
+        raise ReactiveActions::SecurityCheckError, "Security check failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/reactive_actions/configuration.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
-# ReactiveActions module provides functionality for creating and executing reactive actions in Rails applications
+# ReactiveActions provides functionality for creating and executing reactive actions in Rails applications
 module ReactiveActions
   # Configuration class for ReactiveActions
-  # Manages settings for controller method delegation and instance variable delegation
+  # Manages settings for controller method delegation, instance variable delegation, and rate limiting
   class Configuration
-    attr_accessor :delegated_controller_methods, :delegated_instance_variables
+    attr_accessor :delegated_controller_methods, :delegated_instance_variables, :global_rate_limit, :global_rate_limit_window, :rate_limit_key_generator, :rate_limit_cost_calculator
+
+    # Rate limiting configuration
+    attr_accessor :rate_limiting_enabled, :global_rate_limiting_enabled
 
     def initialize
       # Default methods to delegate
@@ -16,6 +19,23 @@ module ReactiveActions
 
       # Default instance variables to delegate
       @delegated_instance_variables = []
+
+      # Rate limiting defaults - DISABLED by default
+      @rate_limiting_enabled = false           # Master switch for all rate limiting
+      @global_rate_limiting_enabled = false    # Global controller-level rate limiting
+      @global_rate_limit = 600                 # 600 requests per minute (10/second)
+      @global_rate_limit_window = 1.minute     # per minute for responsive rate limiting
+      @rate_limit_key_generator = nil          # Use default logic if nil
+      @rate_limit_cost_calculator = nil        # Use default cost of 1 if nil
+    end
+
+    # Helper methods for checking rate limiting status
+    def rate_limiting_available?
+      @rate_limiting_enabled
+    end
+
+    def global_rate_limiting_active?
+      @rate_limiting_enabled && @global_rate_limiting_enabled
     end
   end