dscf-core 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76a29d2a9907fa50b70a858a3e0a01824f2f6168b54733d5bb22428552add9d2
-  data.tar.gz: e6cc6b64f3eaa57d5b29bed770f9ddeec43d462dd2cd23fa3f4bc8cde97bb1ef
+  metadata.gz: 26fe3945c60e59f5abf2ccff51c02da617f1c063cf19c903c5505567ceed13ca
+  data.tar.gz: 57d0f65ee3a45cb0a8e5560fa90cf99ac1ec6f09ef7c161900eb3357c945ac89
 SHA512:
-  metadata.gz: 23411e23576b4f5fb2a0a32a505b5d21025535b511e63430c1fac639e4a2e5f1417f99caf09a45d9a2c49917d4462faebacbbf17963db7b91daab7ec37cc8ad9
-  data.tar.gz: e368003213a383cb9afcacf105c33c0d1fadd2acb1dd08a3ccc3039d28140cadb328c67cc5637758de604b9b9753bb3f5e96bb0926a75eb6a2ba890b05011e98
+  metadata.gz: a75424cbfffeca3f5205660320c9a6cd8a424680d76368f611feef1e578e7b55f90bcc6a0b44eec22d3d09a0c9621f0eb3fffbb149cc64965fa47a2fefea06a6
+  data.tar.gz: 393d2aac7b201c4e84e66fecba0e54ec510977f5b4996bd9b0371e458f3a991408e9cd0ef6f339421fca5d96b303f4a9bee304b93818ad88ac637fdcf9b3c00e

data/app/controllers/concerns/dscf/core/auditable_controller.rb

@@ -0,0 +1,597 @@
+module Dscf
+  module Core
+    # Custom exception for missing auditable record
+    class AuditableRecordNotFoundError < StandardError; end
+
+    module AuditableController
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_audit_configs, default: []
+        class_attribute :_explicit_auditable_model, default: nil
+
+        before_action :capture_audit_snapshot, if: :audit_needed?
+        after_action :enqueue_audit, if: :audit_needed?
+      end
+
+      class_methods do
+        # DSL: Define what to audit
+        #
+        # Simple format (backwards compatible):
+        #   auditable associated: [:reviews], only: [:status], on: [:approve, :reject]
+        #   auditable only: [:name, :email], on: [:create, :update]
+        #
+        # Advanced format with per-association filters:
+        #   auditable on: [:create, :update],
+        #             only: [:status, :approved_at],          # filter for main record
+        #             except: [:internal_notes],              # exclude for main record
+        #             associated: {
+        #               reviews: { only: [:status, :approved_at] },  # filter for reviews
+        #               comments: { except: [:private_flag] }        # exclude for comments
+        #             }
+        def auditable(associated: [], only: [], except: [], on: [], action: nil, transactional: true)
+          # Validate configuration
+          validate_audit_config!(associated: associated, only: only, except: except, on: on, action: action)
+
+          # Normalize associated to always be a hash internally
+          normalized_associated = normalize_associated_for_config(associated)
+
+          config = {
+            associated: normalized_associated,
+            only: Array(only),
+            except: Array(except),
+            on: Array(on).map(&:to_sym),
+            action: action,
+            transactional: transactional
+          }
+          self._audit_configs += [config]
+        end
+
+        # Normalize associated configuration to hash format
+        # Input: [:reviews, :comments] or { reviews: { only: [:status] }, comments: {} }
+        # Output: { reviews: { only: [...], except: [...] }, comments: { only: nil, except: nil } }
+        private def normalize_associated_for_config(associated)
+          return {} if associated.blank?
+
+          if associated.is_a?(Array)
+            # Old format: [:reviews, :comments] -> convert to hash
+            associated.each_with_object({}) { |name, h| h[name] = {} }
+          elsif associated.is_a?(Hash)
+            # New format: already a hash
+            associated
+          else
+            {}
+          end
+        end
+
+        # Validate audit configuration at definition time
+        def validate_audit_config!(associated:, only:, except:, on:, action:)
+          # Validate associated format
+          if associated.is_a?(Array)
+            Array(associated).each do |assoc|
+              unless assoc.is_a?(Symbol)
+                raise ArgumentError, "auditable associated: must be an array of symbols, got #{assoc.class} for #{assoc.inspect}"
+              end
+            end
+          elsif associated.is_a?(Hash)
+            associated.each do |assoc_name, assoc_config|
+              unless assoc_name.is_a?(Symbol)
+                raise ArgumentError, "auditable associated: hash keys must be symbols, got #{assoc_name.class}"
+              end
+
+              if assoc_config.present? && !assoc_config.is_a?(Hash)
+                raise ArgumentError, "auditable associated: hash values must be hashes with :only/:except, got #{assoc_config.class}"
+              end
+
+              # Validate only/except in association config
+              next unless assoc_config.is_a?(Hash)
+
+              assoc_only = Array(assoc_config[:only])
+              assoc_except = Array(assoc_config[:except])
+              overlap = assoc_only & assoc_except
+              if overlap.any?
+                Rails.logger.warn "⚠️  Auditable config warning: 'only' and 'except' overlap for #{assoc_name}: " \
+                                  "#{overlap.join(', ')}. 'except' will take precedence."
+              end
+            end
+          end
+
+          # Validate only/except don't overlap for main record
+          only_arr = Array(only).map(&:to_sym)
+          except_arr = Array(except).map(&:to_sym)
+          overlap = only_arr & except_arr
+          if overlap.any?
+            Rails.logger.warn "⚠️  Auditable config warning: 'only' and 'except' overlap for fields: " \
+                              "#{overlap.join(', ')}. 'except' will take precedence."
+          end
+
+          # Validate action format
+          if action.present?
+            unless action.is_a?(String) || action.is_a?(Hash)
+              raise ArgumentError, "auditable action: must be a String or Hash, got #{action.class}"
+            end
+
+            if action.is_a?(Hash)
+              action.each do |key, value|
+                unless key.is_a?(Symbol) && value.is_a?(String)
+                  raise ArgumentError, "auditable action: Hash keys must be Symbols and values must be Strings"
+                end
+              end
+            end
+          end
+
+          # Validate on actions
+          on_arr = Array(on).map(&:to_sym)
+          valid_actions = %i[index show create update destroy approve reject request_modification resubmit submit]
+          invalid_actions = on_arr - valid_actions
+          return unless invalid_actions.any? && !Rails.env.production?
+
+          Rails.logger.warn "⚠️  Auditable config warning: Unknown actions detected: #{invalid_actions.join(', ')}. " \
+                            "Make sure these are valid controller actions."
+        end
+
+        # DSL: Explicitly set the model class (optional)
+        def auditable_model(klass)
+          self._explicit_auditable_model = klass
+        end
+
+        # DSL: Define action-specific record resolution (optional)
+        # Override auto-discovery for specific actions where needed
+        #
+        # Example:
+        #   auditable_record_for :approve, -> { @reviewable_resource }
+        #   auditable_record_for :reject, -> { @reviewable_resource }
+        #
+        # Or using a map:
+        #   def auditable_record_map
+        #     {
+        #       approve: -> { @reviewable_resource },
+        #       reject:  -> { @reviewable_resource },
+        #       custom_action: -> { @my_custom_var }
+        #     }
+        #   end
+        def auditable_record_for(action_name, resolver = nil, &block)
+          self._audit_configs ||= []
+          resolver_proc = block || resolver
+
+          raise ArgumentError, "auditable_record_for requires a block or lambda" unless resolver_proc
+
+          # Store in class attribute for later access
+          @_auditable_record_resolvers ||= {}
+          @_auditable_record_resolvers[action_name.to_sym] = resolver_proc
+        end
+
+        def auditable_record_resolvers
+          @_auditable_record_resolvers || {}
+        end
+      end
+
+      private
+
+      # Check if current action needs auditing
+      def audit_needed?
+        return false if _audit_configs.empty?
+
+        _audit_configs.any? { |c| c[:on].empty? || c[:on].include?(action_name.to_sym) }
+      end
+
+      # Step 1: Capture state BEFORE action executes
+      def capture_audit_snapshot
+        @audit_snapshot = {}
+
+        # For create actions, we'll capture after the record is created
+        if action_name.to_sym == :create
+          @audit_snapshot[:is_create] = true
+          @audit_snapshot[:before_main] = nil
+          @audit_snapshot[:before_associated] = {}
+          Rails.logger.debug "Audit: Create action detected, will capture state after creation"
+          return
+        end
+
+        record = resolve_auditable_record
+        return unless record
+
+        # Store record identification
+        @audit_snapshot[:record_id] = record.id
+        @audit_snapshot[:record_type] = record.class.name
+
+        # Capture current state of main record
+        @audit_snapshot[:before_main] = capture_record_state(record)
+
+        # Capture current state of associations
+        @audit_snapshot[:before_associated] = {}
+        active_configs.each do |config|
+          # Handle both array and hash formats for associated
+          assoc_names = config[:associated].is_a?(Hash) ? config[:associated].keys : config[:associated]
+          assoc_names.each do |assoc_name|
+            next unless record.respond_to?(assoc_name)
+
+            begin
+              assoc_records = Array(record.public_send(assoc_name)).compact
+              @audit_snapshot[:before_associated][assoc_name] = assoc_records.map { |r| capture_record_state(r) }
+            rescue StandardError => e
+              Rails.logger.debug "Audit: Could not capture #{assoc_name}: #{e.message}"
+            end
+          end
+        end
+
+        # Clear memoization to allow fresh resolution in after_action
+        # This handles cases where controllers reload/modify the record (e.g., Common module)
+        remove_instance_variable(:@resolve_auditable_record) if defined?(@resolve_auditable_record)
+      rescue StandardError => e
+        Rails.logger.warn "Audit snapshot failed: #{e.message}"
+        @audit_snapshot = nil
+      end
+
+      # Step 2: Enqueue audit job AFTER action completes
+      def enqueue_audit
+        Rails.logger.debug "Audit: enqueue_audit called for #{action_name}"
+
+        unless @audit_snapshot.present?
+          Rails.logger.debug "Audit: No snapshot present, skipping"
+          return
+        end
+
+        # For create actions, check early if we should skip auditing
+        # This prevents misleading error logs for validation failures
+        if @audit_snapshot[:is_create]
+          # Try to find the record WITHOUT triggering error logging
+          model_klass = _explicit_auditable_model || detect_model_class
+          record = find_created_record_quietly(model_klass)
+
+          if record.nil? || !record.persisted?
+            Rails.logger.debug "Audit: Skipping failed create (record not persisted)"
+            return
+          end
+
+          # Set record info for successful create
+          @audit_snapshot[:record_id] = record.id
+          @audit_snapshot[:record_type] = record.class.name
+          Rails.logger.debug "Audit: Set record info for create action"
+        end
+
+        # Now resolve the record (for both create and other actions)
+        record = resolve_auditable_record
+
+        # For non-create actions, fail fast if we can't find the record
+        unless record
+          # CRITICAL: Fail fast if we can't find the record
+          log_resolution_failure(detect_model_class, action_name.to_sym)
+          return
+        end
+
+        Rails.logger.debug "Audit: Found record #{record.class.name}##{record.id}"
+
+        # Capture state AFTER action
+        after_main = capture_record_state(record)
+        after_associated = {}
+
+        active_configs.each do |config|
+          # Handle both array and hash formats for associated
+          assoc_names = config[:associated].is_a?(Hash) ? config[:associated].keys : config[:associated]
+          assoc_names.each do |assoc_name|
+            next unless record.respond_to?(assoc_name)
+
+            begin
+              # Reload association to get fresh state
+              record.association(assoc_name).reload if record.association(assoc_name).loaded?
+              assoc_records = Array(record.public_send(assoc_name)).compact
+              after_associated[assoc_name] = assoc_records.map { |r| capture_record_state(r) }
+              Rails.logger.debug "Audit: Captured #{assoc_records.count} #{assoc_name} records"
+            rescue StandardError => e
+              Rails.logger.debug "Audit: Could not capture after state for #{assoc_name}: #{e.message}"
+            end
+          end
+        end
+
+        Rails.logger.debug "Audit: Enqueuing job with #{active_configs.count} configs"
+
+        # Check if any config requires transactional safety
+        requires_transaction = active_configs.any? { |c| c[:transactional] != false }
+
+        # Enqueue job with complete snapshot
+        job_args = {
+          record_id: @audit_snapshot[:record_id],
+          record_type: @audit_snapshot[:record_type],
+          before_main: @audit_snapshot[:before_main],
+          after_main: after_main,
+          before_associated: @audit_snapshot[:before_associated] || {},
+          after_associated: after_associated,
+          actor_id: current_actor&.id,
+          actor_type: current_actor&.class&.name,
+          action_name: action_name,
+          controller_name: controller_name,
+          request_uuid: request.uuid,
+          ip_address: request.remote_ip,
+          user_agent: request.user_agent,
+          configs: active_configs.map { |c| c.except(:block) }
+        }
+
+        if requires_transaction
+          # For critical actions, ensure audit is enqueued synchronously within transaction
+          # This prevents data commits without corresponding audit trail
+          begin
+            AuditLoggerJob.perform_later(**job_args)
+            Rails.logger.debug "Audit: Job enqueued successfully (transactional)"
+          rescue StandardError => e
+            # Re-raise to trigger transaction rollback
+            Rails.logger.error "CRITICAL: Audit enqueue failed - transaction will rollback: #{e.message}"
+            raise Dscf::Core::AuditableRecordNotFoundError,
+                  "Critical Audit Failure: Could not enqueue audit job. Transaction rolled back to prevent untracked changes."
+          end
+        else
+          # For non-critical actions, log errors but don't block the transaction
+          AuditLoggerJob.perform_later(**job_args)
+          Rails.logger.debug "Audit: Job enqueued successfully (non-transactional)"
+        end
+      rescue Dscf::Core::AuditableRecordNotFoundError
+        # Re-raise audit errors to trigger rollback
+        raise
+      rescue StandardError => e
+        # Handle other unexpected errors based on transactional requirement
+        Rails.logger.error "Audit enqueue failed: #{e.message}\n#{e.backtrace.first(5).join("\n")}"
+        requires_transaction = active_configs.any? { |c| c[:transactional] != false }
+        if requires_transaction
+          raise Dscf::Core::AuditableRecordNotFoundError,
+                "Critical Audit Failure: Unexpected error during audit enqueue. Transaction rolled back."
+        end
+      end
+
+      # Capture complete state of a record
+      def capture_record_state(record)
+        return nil unless record&.persisted?
+
+        {
+          id: record.id,
+          type: record.class.name,
+          attributes: record.attributes.dup,
+          timestamp: Time.current.to_f
+        }
+      rescue StandardError => e
+        Rails.logger.debug "Could not capture record state: #{e.message}"
+        nil
+      end
+
+      # Get active audit configs for current action
+      def active_configs
+        _audit_configs.select { |c| c[:on].empty? || c[:on].include?(action_name.to_sym) }
+      end
+
+      # Resolve the main record being audited
+      def resolve_auditable_record
+        return @resolve_auditable_record if defined?(@resolve_auditable_record)
+
+        @resolve_auditable_record = perform_record_resolution
+      end
+
+      # Perform the actual record resolution logic
+      def perform_record_resolution
+        model_klass = _explicit_auditable_model || detect_model_class
+        return nil unless model_klass.respond_to?(:ancestors) && model_klass.ancestors.include?(ActiveRecord::Base)
+
+        current_action = action_name.to_sym
+
+        # Priority 0: Action-specific resolver (explicit configuration via DSL)
+        resolver = self.class.auditable_record_resolvers[current_action]
+        if resolver
+          begin
+            record = instance_exec(&resolver)
+            if record.is_a?(model_klass)
+              Rails.logger.debug "Audit: Found record via action-specific resolver for :#{current_action}"
+              return record
+            elsif record.present?
+              Rails.logger.warn "Audit: Action-specific resolver for :#{current_action} returned " \
+                                "#{record.class.name}, expected #{model_klass.name}"
+            end
+          rescue StandardError => e
+            Rails.logger.error "Audit: Action-specific resolver for :#{current_action} failed: #{e.message}"
+          end
+        end
+
+        # Priority 1: Instance method map (auditable_record_map)
+        if respond_to?(:auditable_record_map, true)
+          begin
+            record_map = auditable_record_map
+            if record_map.is_a?(Hash) && record_map[current_action]
+              resolver_proc = record_map[current_action]
+              record = instance_exec(&resolver_proc)
+              if record.is_a?(model_klass)
+                Rails.logger.debug "Audit: Found record via auditable_record_map for :#{current_action}"
+                return record
+              end
+            end
+          rescue StandardError => e
+            Rails.logger.warn "Audit: auditable_record_map failed for :#{current_action}: #{e.message}"
+          end
+        end
+
+        # Priority 2: Generic hook method (auditable_record)
+        if respond_to?(:auditable_record, true)
+          record = auditable_record
+          if record.is_a?(model_klass)
+            Rails.logger.debug "Audit: Found record via auditable_record hook"
+            return record
+          end
+        end
+
+        # Priority 3: Check ALL instance variables for objects of the model class
+        instance_variables.each do |ivar|
+          # Skip internal audit instance variables
+          next if ivar.to_s.start_with?("@__")
+
+          obj = instance_variable_get(ivar)
+          if obj.is_a?(model_klass)
+            Rails.logger.debug "Audit: Found record via instance variable #{ivar}"
+            return obj
+          end
+        end
+
+        # Priority 4: Try standard Rails @model_name pattern (e.g., @business)
+        ivar_name = "@#{model_klass.name.demodulize.underscore}"
+        if instance_variable_defined?(ivar_name)
+          obj = instance_variable_get(ivar_name)
+          if obj.is_a?(model_klass)
+            Rails.logger.debug "Audit: Found record via naming convention #{ivar_name}"
+            return obj
+          end
+        end
+
+        # Priority 5: Try finding by params[:id] (for show/update/delete actions)
+        if params[:id].present? && current_action != :create
+          begin
+            record = model_klass.find(params[:id])
+            Rails.logger.debug "Audit: Found record via params[:id]"
+            return record
+          rescue ActiveRecord::RecordNotFound, ArgumentError
+            # Record not found or invalid ID
+          end
+        end
+
+        # Priority 6: For create actions, check if a record was just created
+        if current_action == :create
+          # Try to find the most recently created record
+          # This is a fallback for controllers that don't set instance variables
+          recent_record = model_klass.order(created_at: :desc).first
+          if recent_record && recent_record.created_at > 5.seconds.ago
+            Rails.logger.debug "Audit: Found record via recent creation"
+            return recent_record
+          end
+        end
+
+        # FAIL-FAST: Log helpful error message with configuration instructions
+        log_resolution_failure(model_klass, current_action)
+        nil
+      rescue StandardError => e
+        Rails.logger.error "Audit: Failed to resolve record for #{model_klass}: #{e.message}\n#{e.backtrace.first(3).join("\n")}"
+        nil
+      end
+
+      # Handle missing auditable record with environment-aware fail-fast behavior
+      #
+      # This method implements a critical safety feature:
+      # - In development/test: Raises detailed error with full diagnostic info
+      # - In production: Raises concise error and logs full details
+      #
+      # @param model_class [Class] The model class that couldn't be resolved
+      # @param action [Symbol] The controller action being audited
+      # @raise [Dscf::Core::AuditableRecordNotFoundError] Always raises to halt transaction
+      def log_resolution_failure(model_class, action)
+        # Safely collect instance variable information
+        instance_vars_info = instance_variables.filter_map do |v|
+          obj = instance_variable_get(v)
+          "  - #{v} (#{obj.class.name})"
+        rescue StandardError
+          nil
+        end.join("\n")
+
+        # Build comprehensive diagnostic message
+        detailed_message = <<~ERROR
+          ═══════════════════════════════════════════════════════════════════════════
+          🚨 AUDITABLE SYSTEM ERROR: Could not resolve record for audit logging
+          ═══════════════════════════════════════════════════════════════════════════
+
+          Controller: #{self.class.name}
+          Action: #{action}
+          Model: #{model_class.name}
+
+          The Auditable system tried to find the #{model_class.name} record but failed.
+
+          💡 SOLUTION: Define an action-specific resolver in your controller:
+
+          Option 1 - Using auditable_record_map (recommended for multiple actions):
+          ─────────────────────────────────────────────────────────────────────────
+          private
+
+          def auditable_record_map
+            {
+              #{action}: -> { @your_instance_variable }
+            }
+          end
+
+          Option 2 - Using class-level DSL:
+          ─────────────────────────────────────────────────────────────────────────
+          auditable_record_for :#{action}, -> { @your_instance_variable }
+
+          Option 3 - Using a generic hook (for all actions):
+          ─────────────────────────────────────────────────────────────────────────
+          private
+
+          def auditable_record
+            @your_instance_variable
+          end
+
+          📋 Available instance variables in controller:
+          #{instance_vars_info.presence || '  (none found)'}
+
+          ═══════════════════════════════════════════════════════════════════════════
+        ERROR
+
+        # Always log the full detailed message
+        Rails.logger.error(detailed_message)
+
+        # Environment-specific behavior
+        raise Dscf::Core::AuditableRecordNotFoundError, detailed_message unless Rails.env.production?
+
+        Rails.logger.error("[CRITICAL] Audit system failed to resolve #{model_class.name} for action :#{action} in #{self.class.name}")
+
+        # Raise concise error that will halt the transaction
+        raise Dscf::Core::AuditableRecordNotFoundError,
+              "Critical Audit Failure: Could not resolve auditable record for #{model_class.name}##{action}. " \
+              "This transaction has been rolled back to prevent untracked data changes. " \
+              "Check application logs for detailed diagnostic information."
+      end
+
+      # Find created record without triggering error logging
+      # This is used for create actions to check if record was saved before attempting full resolution
+      # @param model_klass [Class] The model class to search for
+      # @return [ActiveRecord::Base, nil] The found record or nil
+      def find_created_record_quietly(model_klass)
+        return nil unless model_klass.respond_to?(:ancestors) && model_klass.ancestors.include?(ActiveRecord::Base)
+
+        # Priority 1: Check ALL instance variables for objects of the model class
+        instance_variables.each do |ivar|
+          # Skip internal instance variables
+          next if ivar.to_s.start_with?("@__", "@audit")
+
+          obj = instance_variable_get(ivar)
+          return obj if obj.is_a?(model_klass)
+        end
+
+        # Priority 2: Try standard Rails @model_name pattern (e.g., @business_type)
+        ivar_name = "@#{model_klass.name.demodulize.underscore}"
+        if instance_variable_defined?(ivar_name)
+          obj = instance_variable_get(ivar_name)
+          return obj if obj.is_a?(model_klass)
+        end
+
+        # Priority 3: Try finding the most recently created record (fallback)
+        recent_record = model_klass.order(created_at: :desc).first
+        return recent_record if recent_record && recent_record.created_at > 5.seconds.ago
+
+        nil
+      rescue StandardError => e
+        Rails.logger.debug "Audit: Could not quietly find created record: #{e.message}"
+        nil
+      end
+
+      # Auto-detect model class from controller name
+      def detect_model_class
+        model_name = controller_name.classify
+        namespace = self.class.name.deconstantize
+
+        if namespace.present? && namespace != "Object"
+          "#{namespace}::#{model_name}".safe_constantize
+        else
+          model_name.safe_constantize
+        end
+      end
+
+      # Get current actor (user performing the action)
+      def current_actor
+        return @current_actor if defined?(@current_actor)
+
+        @current_actor = current_user if respond_to?(:current_user, true)
+      end
+    end
+  end
+end

data/app/controllers/concerns/dscf/core/common.rb

@@ -103,7 +103,11 @@ module Dscf
         end
 
         if obj.save
+          # Store in instance variable for auditing and other concerns
+          @obj = obj
+
           obj = @clazz.includes(eager_loaded_associations).find(obj.id) if eager_loaded_associations.present?
+          @obj = obj  # Update with reloaded version
 
           includes = serializer_includes_for_action(:create)
           options[:include] = includes if includes.present?
@@ -135,6 +139,7 @@ module Dscf
 
         if obj.update(model_params)
           obj = @clazz.includes(eager_loaded_associations).find(obj.id) if eager_loaded_associations.present?
+          @obj = obj  # Update with reloaded version for auditing
 
           includes = serializer_includes_for_action(:update)
           options[:include] = includes if includes.present?