rails_onboarding 0.6.1

data/lib/rails_onboarding/error_recovery.rb

@@ -0,0 +1,173 @@
+module RailsOnboarding
+  # Error Recovery Service
+  # Handles failed steps gracefully with retry logic and error state management
+  class ErrorRecovery
+    MAX_RETRIES = 3
+    RETRY_DELAY = 2.seconds
+
+    class << self
+      # Execute a block with error recovery
+      #
+      # @param user [User] The user performing the action
+      # @param action [Symbol] The action being performed
+      # @param max_retries [Integer] Maximum number of retries
+      # @yield The block to execute
+      # @return [Boolean] True if successful, false otherwise
+      def with_recovery(user, action, max_retries: MAX_RETRIES, &block)
+        attempt = 0
+        last_error = nil
+
+        loop do
+          attempt += 1
+
+          begin
+            result = block.call
+            clear_error_state(user, action)
+            return result
+          rescue StandardError => e
+            last_error = e
+            Rails.logger.error("Error in #{action} (attempt #{attempt}/#{max_retries}): #{e.message}")
+            Rails.logger.error(e.backtrace.join("\n")) if Rails.env.development?
+
+            record_error(user, action, e, attempt)
+
+            break if attempt >= max_retries
+
+            sleep RETRY_DELAY if defined?(sleep)
+          end
+        end
+
+        # All retries failed
+        mark_as_failed(user, action, last_error)
+        false
+      end
+
+      # Record an error for analytics and debugging
+      def record_error(user, action, error, attempt)
+        return unless user && error
+
+        error_data = {
+          action: action.to_s,
+          error_class: error.class.name,
+          error_message: error.message,
+          attempt: attempt,
+          timestamp: Time.current.iso8601
+        }
+
+        # Store in user's error log if available
+        if user.respond_to?(:onboarding_errors)
+          user.onboarding_errors ||= []
+          user.onboarding_errors << error_data
+          user.save(validate: false) rescue nil
+        end
+
+        # Track in analytics
+        if defined?(RailsOnboarding::AnalyticsEvent)
+          RailsOnboarding::AnalyticsEvent.track_custom_event(
+            user: user,
+            event_name: "onboarding_error",
+            event_data: error_data
+          )
+        end
+      end
+
+      # Mark an action as failed after all retries
+      def mark_as_failed(user, action, error)
+        return unless user
+
+        if user.respond_to?(:onboarding_failed_actions)
+          user.onboarding_failed_actions ||= []
+          user.onboarding_failed_actions << {
+            action: action.to_s,
+            error: error&.message,
+            failed_at: Time.current.iso8601
+          }
+          user.save(validate: false) rescue nil
+        end
+
+        Rails.logger.error("Action #{action} failed for user #{user.id} after all retries")
+      end
+
+      # Clear error state for a successful action
+      def clear_error_state(user, action)
+        return unless user
+
+        if user.respond_to?(:onboarding_failed_actions)
+          user.onboarding_failed_actions ||= []
+          user.onboarding_failed_actions.reject! { |a| a[:action] == action.to_s }
+          user.save(validate: false) rescue nil
+        end
+      end
+
+      # Check if user has any failed actions
+      def has_errors?(user)
+        return false unless user&.respond_to?(:onboarding_failed_actions)
+        user.onboarding_failed_actions&.any? || false
+      end
+
+      # Get failed actions for a user
+      def failed_actions(user)
+        return [] unless user&.respond_to?(:onboarding_failed_actions)
+        user.onboarding_failed_actions || []
+      end
+
+      # Retry a failed action
+      def retry_failed_action(user, action, &block)
+        clear_error_state(user, action)
+        with_recovery(user, action, &block)
+      end
+
+      # Reset all errors for a user
+      def reset_errors(user)
+        return unless user
+
+        if user.respond_to?(:onboarding_errors=)
+          user.onboarding_errors = []
+        end
+
+        if user.respond_to?(:onboarding_failed_actions=)
+          user.onboarding_failed_actions = []
+        end
+
+        user.save(validate: false) rescue nil
+      end
+
+      # Retry with exponential backoff
+      def with_exponential_backoff(max_attempts: 3, base_delay: 1, max_delay: 30, exponential_base: 2)
+        attempt = 0
+        begin
+          attempt += 1
+          yield
+        rescue StandardError => e
+          if attempt < max_attempts
+            delay = [ base_delay * (exponential_base ** (attempt - 1)), max_delay ].min
+            Rails.logger.warn "Attempt #{attempt} failed: #{e.message}. Retrying in #{delay}s..."
+            sleep delay
+            retry
+          else
+            Rails.logger.error "All #{max_attempts} attempts failed: #{e.message}"
+            raise
+          end
+        end
+      end
+
+      # Execute with timeout
+      def with_timeout(seconds: 30)
+        Timeout.timeout(seconds) do
+          yield
+        end
+      rescue Timeout::Error => e
+        Rails.logger.error "Operation timed out after #{seconds} seconds"
+        raise
+      end
+
+      # Execute with fallback value
+      def with_fallback(fallback_value = nil)
+        yield
+      rescue StandardError => e
+        Rails.logger.warn "Operation failed, using fallback: #{e.message}"
+        fallback_value
+      end
+    end
+  end
+end

data/lib/rails_onboarding/lazy_loading.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  # Lazy Loading module for performance optimization
+  #
+  # This module provides helpers for lazy loading onboarding components
+  # to improve initial page load times and reduce unnecessary processing
+  module LazyLoading
+    extend ActiveSupport::Concern
+
+    included do
+      # Class-level configuration for lazy loading
+      class_attribute :lazy_loading_enabled, default: true
+      class_attribute :lazy_load_threshold, default: 1000 # Load data only when user count < threshold
+    end
+
+    class_methods do
+      # Scope for users who need onboarding (optimized query)
+      #
+      # @return [ActiveRecord::Relation]
+      def needs_onboarding
+        where(onboarding_completed: false)
+          .where("created_at > ?", 1.hour.ago)
+      end
+
+      # Scope for users currently in onboarding
+      #
+      # @return [ActiveRecord::Relation]
+      def in_onboarding
+        where(onboarding_completed: false)
+          .where.not(onboarding_current_step: nil)
+      end
+
+      # Batch load onboarding states for multiple users
+      # Reduces N+1 queries when displaying lists
+      #
+      # @param user_ids [Array<Integer>] User IDs to load
+      # @return [Hash] Hash of user_id => onboarding_state
+      def batch_load_onboarding_states(user_ids)
+        return {} if user_ids.empty?
+
+        where(id: user_ids)
+          .pluck(:id, :onboarding_completed, :onboarding_current_step)
+          .each_with_object({}) do |(id, completed, step), hash|
+            hash[id] = {
+              completed: completed,
+              current_step: step
+            }
+          end
+      end
+
+      # Count users in each onboarding step (cached for performance)
+      #
+      # @param ttl [Integer] Cache TTL in seconds
+      # @return [Hash] Step name => count
+      def onboarding_step_counts(ttl: 300)
+        cache_key = "rails_onboarding:step_counts"
+        Rails.cache.fetch(cache_key, expires_in: ttl) do
+          in_onboarding
+            .group(:onboarding_current_step)
+            .count
+        end
+      end
+    end
+
+    # Lazy load current step data only when needed
+    #
+    # @return [Hash, nil] Step data
+    def lazy_current_step
+      return @lazy_current_step if defined?(@lazy_current_step)
+
+      @lazy_current_step = if lazy_load_enabled?
+        current_onboarding_step
+      else
+        nil
+      end
+    end
+
+    # Lazy load next step data only when needed
+    #
+    # @return [Hash, nil] Next step data
+    def lazy_next_step
+      return @lazy_next_step if defined?(@lazy_next_step)
+
+      @lazy_next_step = if lazy_load_enabled?
+        next_onboarding_step
+      else
+        nil
+      end
+    end
+
+    # Lazy load available milestones
+    #
+    # @return [Array<Hash>] Available milestones
+    def lazy_milestones_available
+      return @lazy_milestones_available if defined?(@lazy_milestones_available)
+
+      @lazy_milestones_available = if lazy_load_enabled? && RailsOnboarding.configuration.enable_milestones
+        milestones_available
+      else
+        []
+      end
+    end
+
+    # Lazy load tooltips only when on a page that needs them
+    #
+    # @param page_context [String] Current page or controller action
+    # @return [Hash] Available tooltips for current page
+    def lazy_tooltips_for_page(page_context)
+      return {} unless lazy_load_enabled?
+      return {} unless RailsOnboarding.configuration.enable_tooltips
+
+      cache_key = "rails_onboarding:user:#{id}:tooltips:#{page_context}"
+      Rails.cache.fetch(cache_key, expires_in: 600) do
+        tooltips = {}
+        RailsOnboarding.configuration.feature_tooltips.each do |feature, config|
+          # Only include tooltips relevant to current page
+          if feature.include?(page_context) && show_feature_tooltip?(feature)
+            tooltips[feature] = config
+          end
+        end
+        tooltips
+      end
+    end
+
+    # Check if lazy loading should be enabled for this user
+    # based on both the enabled flag and user count threshold
+    #
+    # @return [Boolean]
+    def lazy_load_enabled?
+      return false unless self.class.lazy_loading_enabled
+
+      # Use ActiveRecord's count with uncached query to ensure fresh count
+      # This works better with Rails test transactions
+      count = self.class.uncached { self.class.count }
+
+      count < self.class.lazy_load_threshold
+    end
+
+    # Preload onboarding data for this user
+    # Call this in controller before rendering to avoid N+1
+    #
+    # @return [Hash] Preloaded data
+    def preload_onboarding_data
+      {
+        needs_onboarding: needs_onboarding?,
+        current_step: current_onboarding_step,
+        next_step: next_onboarding_step,
+        progress: onboarding_progress,
+        milestones: RailsOnboarding.configuration.enable_milestones ? achieved_milestones : [],
+        milestone_points: RailsOnboarding.configuration.enable_milestones ? total_milestone_points : 0
+      }
+    end
+  end
+end

data/lib/rails_onboarding/multi_tenant.rb

@@ -0,0 +1,306 @@
+module RailsOnboarding
+  # Multi-Tenant Support
+  # Allows different onboarding configurations per organization/tenant
+  class MultiTenant
+    class << self
+      # Storage for organization-specific configurations (by ID)
+      def organization_configurations
+        @organization_configurations ||= {}
+      end
+
+      # Merged configuration is cached per organization ID so repeated lookups
+      # (every onboarding request) don't re-merge the same hash every time.
+      # Invalidated whenever that organization is reconfigured or cleared.
+      def merged_configuration_cache
+        @merged_configuration_cache ||= {}
+      end
+
+      # Configure onboarding for a specific organization by ID
+      #
+      # @param organization_id [Integer, String] The organization ID
+      # @yield [config] Configuration object to customize
+      def configure_for_organization(organization_id)
+        config = OrganizationConfig.new(organization_id)
+        yield config if block_given?
+        organization_configurations[organization_id] = config.to_hash
+        merged_configuration_cache.delete(organization_id)
+      end
+
+      # Clear all organization configurations (useful for testing)
+      def clear_all_configurations
+        @organization_configurations = {}
+        @merged_configuration_cache = {}
+      end
+
+      # Get configuration for a specific tenant
+      #
+      # @param tenant [Object, Integer, String] The tenant object or organization ID
+      # @return [Hash] Tenant-specific configuration
+      def configuration_for(tenant)
+        return default_configuration unless tenant
+
+        # Check if tenant is an ID (for organization_configurations lookup)
+        if tenant.is_a?(Integer) || tenant.is_a?(String)
+          return merged_configuration_cache[tenant] ||= begin
+            stored_config = organization_configurations[tenant]
+            stored_config ? merge_configurations(default_configuration, stored_config) : default_configuration
+          end
+        end
+
+        # Check if tenant has custom configuration
+        tenant_config = if tenant.respond_to?(:onboarding_configuration)
+                          tenant.onboarding_configuration
+        elsif tenant.respond_to?(:onboarding_config)
+                          tenant.onboarding_config
+        end
+
+        return default_configuration unless tenant_config
+
+        # Merge with default configuration
+        merge_configurations(default_configuration, parse_config(tenant_config))
+      end
+
+      # Get steps for a specific tenant
+      #
+      # @param tenant [Object] The tenant object
+      # @return [Array<Hash>] Array of step configurations
+      def steps_for(tenant)
+        config = configuration_for(tenant)
+        config[:steps] || RailsOnboarding.configuration.steps
+      end
+
+      # Get feature tooltips for a specific tenant
+      #
+      # @param tenant [Object] The tenant object
+      # @return [Hash] Feature tooltip configurations
+      def tooltips_for(tenant)
+        config = configuration_for(tenant)
+        config[:feature_tooltips] || RailsOnboarding.configuration.feature_tooltips
+      end
+
+      # Get milestones for a specific tenant
+      #
+      # @param tenant [Object] The tenant object
+      # @return [Array<Hash>] Milestone configurations
+      def milestones_for(tenant)
+        config = configuration_for(tenant)
+        config[:milestones] || RailsOnboarding.configuration.milestones
+      end
+
+      # Check if a feature is enabled for a tenant
+      #
+      # @param tenant [Object] The tenant object
+      # @param feature [Symbol] The feature to check
+      # @return [Boolean] True if feature is enabled
+      def feature_enabled?(tenant, feature)
+        config = configuration_for(tenant)
+
+        case feature
+        when :tooltips
+          config[:enable_tooltips] != false
+        when :milestones
+          config[:enable_milestones] != false
+        when :analytics
+          config[:enable_analytics] != false
+        when :ab_testing
+          config[:enable_ab_testing] == true
+        when :personalization
+          config[:personalization_enabled] == true
+        else
+          false
+        end
+      end
+
+      # Apply tenant configuration to current context, for the duration of the
+      # block only. This does NOT touch RailsOnboarding.configuration itself -
+      # it sets a thread/fiber-local override (RailsOnboarding::Current) that
+      # Configuration's readers consult first, so concurrent requests for
+      # other tenants (or no tenant) are never affected, and everything is
+      # automatically cleared even if this method's own `ensure` never ran
+      # (Rails resets CurrentAttributes around every request and job).
+      #
+      # @param tenant [Object] The tenant object
+      # @yield Block to execute with tenant configuration
+      def with_tenant_configuration(tenant)
+        return yield unless tenant
+
+        previous_overrides = RailsOnboarding::Current.tenant_overrides
+        RailsOnboarding::Current.tenant_overrides = tenant_config_overrides(tenant)
+
+        yield
+      ensure
+        RailsOnboarding::Current.tenant_overrides = previous_overrides
+      end
+
+      # Get organization ID for user
+      #
+      # @param user [User] The user object
+      # @return [Integer, String, nil] The organization ID
+      def organization_for_user(user)
+        return nil unless user
+
+        # Try to get organization_id directly
+        if user.respond_to?(:organization_id)
+          return user.organization_id
+        end
+
+        # Otherwise, get tenant and extract its ID
+        tenant = tenant_from_user(user)
+        tenant&.id
+      end
+
+      # Get tenant from user
+      #
+      # @param user [User] The user object
+      # @return [Object, nil] The tenant object
+      def tenant_from_user(user)
+        return nil unless user
+
+        # Try common tenant associations
+        if user.respond_to?(:organization)
+          user.organization
+        elsif user.respond_to?(:account)
+          user.account
+        elsif user.respond_to?(:tenant)
+          user.tenant
+        elsif user.respond_to?(:team)
+          user.team
+        elsif user.respond_to?(:company)
+          user.company
+        end
+      end
+
+      # Set custom configuration for a tenant
+      #
+      # @param tenant [Object] The tenant object
+      # @param config [Hash] Configuration hash
+      def set_configuration(tenant, config)
+        return unless tenant
+
+        if tenant.respond_to?(:onboarding_configuration=)
+          tenant.onboarding_configuration = config.to_json
+          tenant.save
+        elsif tenant.respond_to?(:update)
+          tenant.update(onboarding_configuration: config.to_json) rescue nil
+        end
+      end
+
+      # Copy configuration from one tenant to another
+      #
+      # @param source_tenant [Object] Source tenant
+      # @param target_tenant [Object] Target tenant
+      def copy_configuration(source_tenant, target_tenant)
+        config = configuration_for(source_tenant)
+        set_configuration(target_tenant, config)
+      end
+
+      # Reset tenant configuration to default
+      #
+      # @param tenant [Object] The tenant object
+      def reset_configuration(tenant)
+        return unless tenant
+
+        if tenant.respond_to?(:onboarding_configuration=)
+          tenant.onboarding_configuration = nil
+          tenant.save
+        end
+      end
+
+      private
+
+      def default_configuration
+        {
+          steps: RailsOnboarding.configuration.steps,
+          feature_tooltips: RailsOnboarding.configuration.feature_tooltips,
+          milestones: RailsOnboarding.configuration.milestones,
+          enable_tooltips: RailsOnboarding.configuration.enable_tooltips,
+          enable_milestones: RailsOnboarding.configuration.enable_milestones,
+          enable_analytics: RailsOnboarding.configuration.enable_analytics,
+          enable_ab_testing: RailsOnboarding.configuration.enable_ab_testing,
+          personalization_enabled: RailsOnboarding.configuration.personalization_enabled,
+          redirect_after_completion: RailsOnboarding.configuration.redirect_after_completion,
+          redirect_after_skip: RailsOnboarding.configuration.redirect_after_skip
+        }
+      end
+
+      def parse_config(config_data)
+        return {} unless config_data
+
+        parsed = if config_data.is_a?(String)
+                   JSON.parse(config_data)
+        else
+                   config_data
+        end
+
+        parsed.deep_symbolize_keys
+      rescue JSON::ParserError => e
+        Rails.logger.error("Failed to parse tenant configuration: #{e.message}")
+        {}
+      end
+
+      def merge_configurations(base, override)
+        base.deep_merge(override) do |key, base_val, override_val|
+          # For arrays, use override completely
+          if base_val.is_a?(Array) && override_val.is_a?(Array)
+            override_val
+          else
+            override_val.nil? ? base_val : override_val
+          end
+        end
+      end
+
+      # Builds the RailsOnboarding::Current override hash for +tenant+, only
+      # including keys that should actually override the process-wide config -
+      # mirrors the guards the old mutation-based implementation used, so a
+      # tenant config that hasn't customized a given setting still falls
+      # through to the global default instead of overriding it with nil/false.
+      def tenant_config_overrides(tenant)
+        config = configuration_for(tenant)
+        overrides = {}
+
+        overrides[:steps] = config[:steps] if config[:steps]
+        overrides[:feature_tooltips] = config[:feature_tooltips] if config[:feature_tooltips]
+        overrides[:milestones] = config[:milestones] if config[:milestones]
+        overrides[:enable_tooltips] = config[:enable_tooltips] unless config[:enable_tooltips].nil?
+        overrides[:enable_milestones] = config[:enable_milestones] unless config[:enable_milestones].nil?
+
+        overrides
+      end
+    end
+  end
+
+  # Configuration object for organization-specific settings
+  class OrganizationConfig
+    attr_accessor :steps, :feature_tooltips, :milestones,
+                  :enable_tooltips, :enable_milestones, :enable_analytics,
+                  :enable_ab_testing, :personalization_enabled,
+                  :redirect_after_completion, :redirect_after_skip
+
+    def initialize(organization_id)
+      @organization_id = organization_id
+      @steps = []
+      @feature_tooltips = {}
+      @milestones = {}
+      @enable_tooltips = true
+      @enable_milestones = true
+      @enable_analytics = true
+      @enable_ab_testing = false
+      @personalization_enabled = false
+    end
+
+    def to_hash
+      {
+        steps: @steps,
+        feature_tooltips: @feature_tooltips,
+        milestones: @milestones,
+        enable_tooltips: @enable_tooltips,
+        enable_milestones: @enable_milestones,
+        enable_analytics: @enable_analytics,
+        enable_ab_testing: @enable_ab_testing,
+        personalization_enabled: @personalization_enabled,
+        redirect_after_completion: @redirect_after_completion,
+        redirect_after_skip: @redirect_after_skip
+      }
+    end
+  end
+end