reactive-actions 0.1.0.pre.alpha.1

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/assets/javascripts/reactive_actions.js

@@ -0,0 +1,100 @@
+// ReactiveActions JavaScript Client for Rails 8
+// ES Module compatible version
+
+class ReactiveActionsClient {
+  constructor() {
+    this.baseUrl = '/reactive_actions/execute';
+  }
+
+  // Get CSRF token from meta tag
+  getCSRFToken() {
+    const metaTag = document.querySelector('meta[name="csrf-token"]');
+    return metaTag ? metaTag.getAttribute('content') : null;
+  }
+
+  // Execute an action with parameters
+  async execute(actionName, actionParams = {}, options = {}) {
+    const method = options.method || 'POST';
+    const contentType = options.contentType || 'application/json';
+    
+    // Build request options
+    const requestOptions = {
+      method: method,
+      headers: {
+        'Content-Type': contentType,
+        'X-Requested-With': 'XMLHttpRequest'
+      },
+      credentials: 'same-origin'
+    };
+    
+    // Add CSRF token if available
+    const csrfToken = this.getCSRFToken();
+    if (csrfToken) {
+      requestOptions.headers['X-CSRF-Token'] = csrfToken;
+    }
+    
+    // Build URL or prepare body based on HTTP method
+    let url = this.baseUrl;
+    if (['GET', 'HEAD'].includes(method.toUpperCase())) {
+      // For GET requests, append parameters to URL
+      const params = new URLSearchParams({
+        action_name: actionName,
+        action_params: JSON.stringify(actionParams)
+      });
+      url = `${url}?${params.toString()}`;
+    } else {
+      // For other methods, send in request body
+      requestOptions.body = JSON.stringify({
+        action_name: actionName,
+        action_params: actionParams
+      });
+    }
+    
+    try {
+      const response = await fetch(url, requestOptions);
+      const data = await response.json();
+      
+      // Add response status and ok to the result
+      return {
+        ...data,
+        status: response.status,
+        ok: response.ok
+      };
+    } catch (error) {
+      console.error('ReactiveActions error:', error);
+      throw error;
+    }
+  }
+
+  // Convenience methods for different HTTP verbs
+  async get(actionName, actionParams = {}, options = {}) {
+    return this.execute(actionName, actionParams, { ...options, method: 'GET' });
+  }
+
+  async post(actionName, actionParams = {}, options = {}) {
+    return this.execute(actionName, actionParams, { ...options, method: 'POST' });
+  }
+
+  async put(actionName, actionParams = {}, options = {}) {
+    return this.execute(actionName, actionParams, { ...options, method: 'PUT' });
+  }
+
+  async patch(actionName, actionParams = {}, options = {}) {
+    return this.execute(actionName, actionParams, { ...options, method: 'PATCH' });
+  }
+
+  async delete(actionName, actionParams = {}, options = {}) {
+    return this.execute(actionName, actionParams, { ...options, method: 'DELETE' });
+  }
+}
+
+// Create and export the instance
+const ReactiveActions = new ReactiveActionsClient();
+
+// For backward compatibility, also expose as global
+if (typeof window !== 'undefined') {
+  window.ReactiveActions = ReactiveActions;
+}
+
+// ES Module export
+export default ReactiveActions;

data/app/controllers/reactive_actions/application_controller.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module ReactiveActions
+  # Base controller for the ReactiveActions engine
+  # Provides common functionality and settings for all controllers in the engine
+  class ApplicationController < ActionController::Base
+    # This controller is the base controller for all controllers in the engine
+    protect_from_forgery with: :exception
+  end
+end

data/app/controllers/reactive_actions/reactive_actions_controller.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module ReactiveActions
+  # Main controller for handling reactive action requests
+  # Processes action execution and manages error handling for the ReactiveActions engine
+  class ReactiveActionsController < ApplicationController
+    # Allow this action to handle any HTTP method
+    def execute
+      ReactiveActions.logger.info "ReactiveActionsController#execute[#{request.method}]: #{params.inspect}"
+      build_reactive_action.run
+    rescue ReactiveActions::Error => e
+      handle_reactive_actions_error(e)
+    rescue StandardError => e
+      handle_standard_error(e)
+    end
+
+    private
+
+    # Build and initialize the action
+    def build_reactive_action
+      initialize_action(extract_action_name, extract_action_params)
+    end
+
+    # Extract and validate action_name parameter
+    def extract_action_name
+      action_name = params[:action_name]
+      raise ReactiveActions::MissingParameterError, 'Missing action_name parameter' if action_name.blank?
+
+      # Sanitize action_name to prevent code injection
+      sanitized_name = action_name.to_s.strip
+      raise ReactiveActions::InvalidParametersError, 'Invalid action_name format' unless sanitized_name.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*\z/)
+
+      sanitized_name
+    end
+
+    # Extract and sanitize action_params with proper strong parameters
+    def extract_action_params
+      raw_params = params[:action_params]
+      return {} if raw_params.blank?
+
+      # For JSON requests, the params might already be a hash
+      if raw_params.is_a?(String)
+        begin
+          parsed_params = JSON.parse(raw_params)
+          permit_nested_params(parsed_params)
+        rescue JSON::ParserError
+          raise ReactiveActions::InvalidParametersError, 'Invalid JSON in action_params'
+        end
+      else
+        # Handle ActionController::Parameters, Hash, or any other object
+        permit_nested_params(raw_params)
+      end
+    end
+
+    # Recursively permit nested parameters
+    # This allows for flexible parameter structures while maintaining security
+    def permit_nested_params(params)
+      case params
+      when ActionController::Parameters, Hash
+        permit_hash_params(params)
+      when Array
+        params.map { |item| permit_nested_params(item) }
+      else
+        sanitize_param_value(params)
+      end
+    end
+
+    # Handle hash-like parameters (ActionController::Parameters or Hash)
+    def permit_hash_params(params)
+      permitted_hash = {}
+      params.each do |key, value|
+        sanitized_key = sanitize_param_key(key)
+        next if sanitized_key.nil?
+
+        permitted_hash[sanitized_key] = permit_nested_params(value)
+      end
+      permitted_hash
+    end
+
+    # Sanitize parameter keys to prevent injection attacks
+    def sanitize_param_key(key)
+      key_str = key.to_s.strip
+
+      # Only allow alphanumeric characters, underscores, and hyphens
+      return nil unless key_str.match?(/\A[a-zA-Z0-9_-]+\z/)
+
+      # Prevent keys that start with dangerous prefixes
+      dangerous_prefixes = %w[__ eval exec system `]
+      return nil if dangerous_prefixes.any? { |prefix| key_str.start_with?(prefix) }
+
+      key_str
+    end
+
+    # Sanitize parameter values based on type
+    def sanitize_param_value(value)
+      return value if safe_primitive_type?(value)
+      return truncate_string(value) if value.is_a?(String)
+
+      # For other types, preserve original value if reasonable
+      value.respond_to?(:to_s) && !value.is_a?(Object) ? truncate_string(value.to_s) : value
+    end
+
+    # Check if value is a safe primitive type that doesn't need sanitization
+    def safe_primitive_type?(value)
+      value.is_a?(Numeric) || value.is_a?(TrueClass) || value.is_a?(FalseClass) ||
+        value.nil? || value.is_a?(Time) || value.is_a?(Date) || value.is_a?(DateTime)
+    end
+
+    # Truncate strings to prevent memory exhaustion
+    def truncate_string(string)
+      max_length = string == string.to_s ? 10_000 : 1_000
+      string.length > max_length ? string[0, max_length] : string
+    end
+
+    def handle_reactive_actions_error(exception)
+      error_mapping = {
+        'ActionNotFoundError' => [:not_found, 'NOT_FOUND'],
+        'MissingParameterError' => [:bad_request, 'MISSING_PARAMETER'],
+        'InvalidParametersError' => [:bad_request, 'INVALID_PARAMETERS'],
+        'UnauthorizedError' => [:forbidden, 'UNAUTHORIZED'],
+        'ActionExecutionError' => [:unprocessable_entity, 'EXECUTION_ERROR']
+      }
+
+      error_type = exception.class.name.demodulize
+      status, code = error_mapping[error_type]
+
+      ReactiveActions.logger.error "#{error_type}: #{exception.message}"
+      render_error(exception, status, code)
+    end
+
+    def handle_standard_error(exception)
+      ReactiveActions.logger.error "Unexpected error: #{exception.message}"
+      render_error(exception, :internal_server_error, 'SERVER_ERROR')
+    end
+
+    # Helper method to render standardized error responses
+    def render_error(exception, status, code)
+      render json: {
+        success: false,
+        error: {
+          type: exception.class.name.demodulize,
+          message: exception.message,
+          code: code
+        }
+      }, status: status
+    end
+
+    # Find and execute the requested action
+    def initialize_action(action_name, action_params)
+      # Convert snake_case action name to CamelCase class name
+      # e.g., "update_user" becomes "UpdateUserAction"
+      class_name = build_class_name(action_name)
+
+      # Find the action class - this will look in several places:
+      # 1. ReactiveActions::{ClassName} (e.g., ReactiveActions::UpdateUserAction)
+      # 2. {ClassName} (e.g., UpdateUserAction) in global namespace
+      action_class = find_action_class(class_name)
+
+      # Initialize the action and return it
+      # Add ** to convert hash to keyword arguments
+      action_class.new(self, **action_params.symbolize_keys)
+    end
+
+    def build_class_name(action_name)
+      class_name = action_name.to_s.camelize
+      # Add "Action" suffix if it doesn't already end with it
+      class_name.end_with?('Action') ? class_name : "#{class_name}Action"
+    end
+
+    # Find an action class using various lookup strategies
+    def find_action_class(class_name)
+      # First try within the ReactiveActions namespace
+      "ReactiveActions::#{class_name}".constantize
+    rescue NameError
+      begin
+        # Then try in the global namespace
+        class_name.constantize
+      rescue NameError
+        raise ReactiveActions::ActionNotFoundError, "Action '#{class_name.sub(/Action$/, '')}' not found"
+      end
+    end
+  end
+end

data/config/initializers/reactive_actions_logger.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+ReactiveActions.logger = Rails.logger
+Rails.logger.level = :debug

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+ReactiveActions::Engine.routes.draw do
+  match '/execute', to: 'reactive_actions#execute', via: %i[get post put patch delete]
+end

data/lib/generators/reactive_actions/install/install_generator.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module ReactiveActions
+  module Generators
+    # Interactive generator for installing ReactiveActions into a Rails application
+    # Prompts user for installation preferences and customization options
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Installs ReactiveActions with interactive configuration'
+
+      # Command line options
+      class_option :skip_routes, type: :boolean, default: false,
+                                 desc: 'Skip adding routes to the application'
+      class_option :skip_javascript, type: :boolean, default: false,
+                                     desc: 'Skip adding JavaScript imports'
+      class_option :skip_example, type: :boolean, default: false,
+                                  desc: 'Skip generating example action'
+      class_option :mount_path, type: :string, default: '/reactive_actions',
+                                desc: 'Custom mount path for ReactiveActions'
+      class_option :quiet, type: :boolean, default: false,
+                           desc: 'Run with minimal output'
+
+      def welcome_message
+        return if options[:quiet]
+
+        say 'Welcome to ReactiveActions installer!', :green
+        say 'This will help you set up ReactiveActions in your Rails application.'
+        say ''
+      end
+
+      def create_initializer
+        if options[:quiet] || yes?('Create ReactiveActions initializer? (recommended)', :green)
+          template 'initializer.rb', 'config/initializers/reactive_actions.rb'
+          say '✓ Created initializer', :green unless options[:quiet]
+        else
+          say '✗ Skipped initializer creation', :yellow
+        end
+      end
+
+      def create_actions_directory
+        if options[:quiet] || yes?('Create app/reactive_actions directory?', :green)
+          empty_directory 'app/reactive_actions'
+          say '✓ Created actions directory', :green unless options[:quiet]
+
+          ask_for_example_action unless options[:skip_example]
+        else
+          say '✗ Skipped actions directory creation', :yellow
+        end
+      end
+
+      def configure_routes
+        return if options[:skip_routes]
+
+        mount_path = determine_mount_path
+        return if mount_path.nil?
+
+        route "mount ReactiveActions::Engine, at: '#{mount_path}'"
+        say "✓ Added route mounting ReactiveActions at #{mount_path}", :green unless options[:quiet]
+      end
+
+      def configure_javascript
+        return if options[:skip_javascript]
+        return unless javascript_needed?
+
+        if options[:quiet] || yes?('Add ReactiveActions JavaScript client?', :green)
+          add_javascript_to_importmap
+          say '✓ Added JavaScript client to importmap', :green unless options[:quiet]
+        else
+          say '✗ Skipped JavaScript configuration', :yellow
+        end
+      end
+
+      def configuration_options
+        return if options[:quiet]
+        return unless yes?('Configure advanced options?', :green)
+
+        configure_delegated_methods
+        configure_logging
+      end
+
+      def installation_summary
+        return if options[:quiet]
+
+        say '', :green
+        say '=' * 60, :green
+        say 'ReactiveActions installation complete!', :bold
+        say '=' * 60, :green
+
+        show_usage_instructions
+      end
+
+      private
+
+      def should_skip_example_action?
+        return true if options[:skip_example]
+        return true if !options[:quiet] && !yes?('Generate example action file?', :green)
+
+        false
+      end
+
+      def example_action_name
+        if options[:quiet]
+          'example'
+        else
+          ask('What should the example action be called?', default: 'example')
+        end
+      end
+
+      def sanitize_action_name(action_name)
+        sanitized = action_name.to_s.strip.underscore
+        sanitized = 'example' if sanitized.blank?
+        sanitized.end_with?('_action') ? sanitized : "#{sanitized}_action"
+      end
+
+      def determine_mount_path
+        return options[:mount_path] if options[:quiet]
+        return nil if options[:skip_routes]
+
+        if yes?('Add ReactiveActions routes to your application?', :green)
+          custom_path = ask('Mount path for ReactiveActions:', default: options[:mount_path])
+          sanitize_mount_path(custom_path)
+        else
+          say '✗ Skipped route configuration', :yellow
+          nil
+        end
+      end
+
+      def sanitize_mount_path(path)
+        sanitized = path.to_s.strip
+        sanitized = options[:mount_path] if sanitized.blank?
+        sanitized.start_with?('/') ? sanitized : "/#{sanitized}"
+      end
+
+      def javascript_needed?
+        using_importmap? || using_sprockets?
+      end
+
+      def using_importmap?
+        File.exist?('config/importmap.rb')
+      end
+
+      def using_sprockets?
+        File.exist?('app/assets/config/manifest.js')
+      end
+
+      def add_javascript_to_importmap
+        if using_importmap?
+          add_to_importmap
+        elsif using_sprockets?
+          add_to_sprockets_manifest
+        else
+          say 'No supported JavaScript setup detected (importmap or sprockets)', :yellow
+        end
+      end
+
+      def add_to_importmap
+        importmap_content = <<~IMPORTMAP
+
+          # ReactiveActions JavaScript client
+          pin "reactive_actions", to: "reactive_actions.js"
+        IMPORTMAP
+
+        append_to_file 'config/importmap.rb', importmap_content
+
+        # Add the import to application.js to ensure it executes
+        add_import_to_application_js
+      end
+
+      def add_import_to_application_js
+        app_js_paths = %w[
+          app/javascript/application.js
+          app/assets/javascripts/application.js
+          app/javascript/controllers/application.js
+        ]
+
+        app_js_path = app_js_paths.find { |path| File.exist?(path) }
+
+        if app_js_path
+          # Check if import already exists
+          app_js_content = File.read(app_js_path)
+          return if app_js_content.include?('import "reactive_actions"')
+
+          import_line = <<~JAVASCRIPT
+
+            // Import ReactiveActions to make it globally available
+            import "reactive_actions"
+          JAVASCRIPT
+
+          append_to_file app_js_path, import_line
+          say "✓ Added ReactiveActions import to #{app_js_path}", :green unless options[:quiet]
+        else
+          say '⚠ Could not find application.js file. Please manually add: import "reactive_actions"', :yellow
+        end
+      end
+
+      def add_to_sprockets_manifest
+        return unless File.exist?('app/assets/config/manifest.js')
+
+        append_to_file 'app/assets/config/manifest.js' do
+          "\n//= link reactive_actions.js\n"
+        end
+      end
+
+      def configure_delegated_methods
+        return unless yes?('Add custom controller methods to delegate to actions?', :green)
+
+        methods = ask('Enter method names (comma-separated):')
+        return if methods.blank?
+
+        method_array = methods.split(',').map(&:strip).map(&:to_sym)
+        add_custom_config('delegated_controller_methods', method_array)
+      end
+
+      def configure_logging
+        log_level = ask('Set logging level:',
+                        limited_to: %w[debug info warn error fatal],
+                        default: 'info')
+
+        add_custom_config('log_level', log_level) unless log_level == 'info'
+      end
+
+      def add_custom_config(option, value)
+        initializer_path = 'config/initializers/reactive_actions.rb'
+        return unless File.exist?(initializer_path)
+
+        config_line = build_config_line(option, value)
+        append_to_file initializer_path, "\n#{config_line}\n"
+      end
+
+      def build_config_line(option, value)
+        case option
+        when 'delegated_controller_methods'
+          "  config.delegated_controller_methods += #{value}"
+        when 'log_level'
+          "ReactiveActions.logger.level = :#{value}"
+        end
+      end
+
+      def show_usage_instructions
+        if yes?('Show usage instructions?', :green)
+          readme 'README' if behavior == :invoke
+        else
+          say 'You can find usage instructions in the ReactiveActions documentation.'
+        end
+      end
+
+      def ask_for_example_action
+        return if should_skip_example_action?
+
+        action_name = example_action_name
+        sanitized_name = sanitize_action_name(action_name)
+
+        template 'example_action.rb', "app/reactive_actions/#{sanitized_name}.rb"
+        say "✓ Created #{sanitized_name}.rb", :green unless options[:quiet]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+===============================================================================
+
+ReactiveActions has been installed successfully!
+
+Routes have been added to your config/routes.rb file:
+  mount ReactiveActions::Engine, at: '/reactive_actions'
+
+You can now access the reactive actions functionality at:
+  http://localhost:3000/reactive_actions/execute
+
+A sample action has been created at:
+  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:
+  https://github.com/IstvanMs/reactive-actions
+
+===============================================================================

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Example reactive action
+# This action demonstrates the basic structure of a reactive action
+class ExampleAction < ReactiveActions::ReactiveAction
+  # The main action logic goes here
+  def action
+    # You can access action parameters via the action_params
+    name = action_params[:name] || 'World'
+
+    # Generate a result hash (optional)
+    @result = {
+      status: :success,
+      message: "Hello, #{name}!"
+    }
+  end
+
+  # Define how to respond to the client
+  def response
+    # You can use controller methods like render
+    render json: {
+      success: true,
+      data: @result
+    }
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# ReactiveActions configuration
+ReactiveActions.configure do |config|
+  # Configure methods to delegate from the controller to action classes
+  # config.delegated_controller_methods += [:custom_method]
+
+  # Configure instance variables to delegate from the controller to action classes
+  # config.delegated_instance_variables += [:custom_variable]
+end
+
+# Set the logger for ReactiveActions
+ReactiveActions.logger = Rails.logger

data/lib/reactive-actions.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'reactive_actions'