dscf-core 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4889901ac24447991c5b303a9a8ecea4853d4ccd0e10a1a6c311d19667ce3bda
-  data.tar.gz: febbd03906d18bd0dd1b24e99a78c5bf9a27b49b55f75c6a27617a852f696dfa
+  metadata.gz: 230e498b674cb3acf80fd9c7637b89c3e8da0e697a108f5d1b8998b9218eda59
+  data.tar.gz: d62246472662f80db9df2478a08afa9eebd163af916aa9a70f408ccbe695bf25
 SHA512:
-  metadata.gz: da46ece55e36f787b949c4147763cffc11ae46b0e7f72c0da91ea7b0ba091dfb59516957ee550c19979d506332b525f2da7d39e496112c8005591e095d198f65
-  data.tar.gz: 0ec263cf5d6b2999ea90af8c839d9eeacf186551a250ba7159d0fe57440c88d4e718048e0a1aeda12638551dd8a715d6011702f61c7b94cbffb09df932e99017
+  metadata.gz: aadfeecee56e8ffc6ade9f47f244a7e313b23e23913dd99636c0bcff48fa53deb029c0461c8f92d4094352932f99f9941c3de5c97987a5f71bad92aec01364e5
+  data.tar.gz: 5ec8e1e44f084814ba4139be60f4f9c306f42eb383aced86d12764c61a205369242a09e72450f98104e7cb15bece45680210473827dbb691d9c05388581b188b

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

@@ -0,0 +1,539 @@
+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
+        # auditable associated: [:reviews], only: [:status], on: [:approve, :reject]
+        # auditable only: [:name, :email], on: [:create, :update]
+        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)
+
+          config = {
+            associated: Array(associated),
+            only: Array(only),
+            except: Array(except),
+            on: Array(on).map(&:to_sym),
+            action: action,
+            transactional: transactional
+          }
+          self._audit_configs += [config]
+        end
+
+        # Validate audit configuration at definition time
+        def validate_audit_config!(associated:, only:, except:, on:, action:)
+          # Validate associated is array of symbols
+          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
+
+          # Validate only/except don't overlap
+          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|
+          config[:associated].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|
+          config[:associated].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?

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

@@ -84,6 +84,7 @@ module Dscf
 
         def default_actions
           {
+            submit: {status: "pending", require_submission_ready: true},
             approve: {status: "approved"},
             reject: {status: "rejected", require_feedback: true},
             request_modification: {status: "modify", require_feedback: true},
@@ -94,9 +95,13 @@ module Dscf
         def default_context_config
           {
             default: {
-              statuses: %w[pending approved rejected modify],
-              initial_status: "pending",
-              transitions: {"pending" => %w[approved rejected modify], "modify" => ["pending"]},
+              statuses: %w[draft pending approved rejected modify],
+              initial_status: "draft",
+              transitions: {
+                "draft" => ["pending"],
+                "pending" => %w[approved rejected modify],
+                "modify" => ["pending"]
+              },
               actions: default_actions
             }
           }
@@ -141,7 +146,7 @@ module Dscf
         self.class.review_action_names.include?(action_name.to_sym)
       end
 
-      def perform_review_action(status:, require_feedback: false, after: nil, update_model: false)
+      def perform_review_action(status:, require_feedback: false, require_submission_ready: false, after: nil, update_model: false)
         begin
           context_config
         rescue ArgumentError => e
@@ -150,6 +155,14 @@ module Dscf
 
         current_review = reviewable_resource.current_review_for(current_review_context)
 
+        # Check if submission is ready (for submit action)
+        if require_submission_ready && !submission_ready?(reviewable_resource)
+          return render_error(
+            errors: ["Resource must be complete and valid before submission"],
+            status: :unprocessable_entity
+          )
+        end
+
         feedback = if require_feedback
                      feedback_data = params[:review_feedback]
                      feedback_data = feedback_data.to_unsafe_h if feedback_data.respond_to?(:to_unsafe_h)
@@ -261,6 +274,15 @@ module Dscf
         # Override for custom auth
       end
 
+      def submission_ready?(resource)
+        # Default implementation - validates the resource is ready for submission
+        # Override this method in your controller for custom validation logic
+        # Return true if ready, false otherwise
+        return true unless resource.respond_to?(:valid?)
+
+        resource.valid?
+      end
+
       def before_review_action(review)
         # Default implementation - can be overridden
         # Check if there's a custom hook method defined