action-audit 1.0.1

data/docs/usage.md

@@ -0,0 +1,347 @@
+# Usage Guide
+
+This guide covers how to use ActionAudit in your Rails controllers and common usage patterns.
+
+## Basic Usage
+
+### Including ActionAudit
+
+Include the `ActionAudit` module in any controller you want to audit:
+
+```ruby
+class UsersController < ApplicationController
+  include ActionAudit
+
+  def create
+    @user = User.create!(user_params)
+    # ActionAudit automatically logs this action after completion
+  end
+
+  def update
+    @user = User.find(params[:id])
+    @user.update!(user_params)
+    # Will log with interpolated parameters
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:name, :email, :role)
+  end
+end
+```
+
+### How It Works
+
+1. **Automatic Hook**: When you include `ActionAudit`, it adds an `after_action :audit_request` callback
+2. **Message Lookup**: After each action, it looks up the corresponding message in your `audit.yml` configuration
+3. **Parameter Interpolation**: It interpolates the message with parameters from `params`
+4. **Logging**: It logs the final message using `Rails.logger`
+
+## Parameter Interpolation
+
+ActionAudit uses Ruby's string interpolation (`%{key}`) to inject parameter values into audit messages.
+
+### Basic Interpolation
+
+```yaml
+# config/audit.yml
+users:
+  create: "Created user %{email}"
+  update: "Updated user %{id} with name %{name}"
+```
+
+```ruby
+class UsersController < ApplicationController
+  include ActionAudit
+
+  def create
+    # If params = { email: "john@example.com", name: "John Doe" }
+    # Will log: "Created user john@example.com"
+  end
+
+  def update
+    # If params = { id: "123", name: "Jane Doe" }
+    # Will log: "Updated user 123 with name Jane Doe"
+  end
+end
+```
+
+### Nested Parameters
+
+ActionAudit automatically flattens nested parameters for interpolation:
+
+```ruby
+# If params = { user: { email: "john@example.com" }, id: "123" }
+# You can reference both %{id} and %{email} in your audit message
+```
+
+### Error Handling
+
+If a parameter referenced in the audit message is missing, ActionAudit handles it gracefully:
+
+```yaml
+users:
+  create: "Created user %{email} with role %{role}"
+```
+
+If `params[:role]` is missing, the log will show:
+```
+Created user john@example.com with role %{role} (interpolation error: key{role} not found)
+```
+
+## Controller Patterns
+
+### Application-Wide Auditing
+
+Include ActionAudit in your `ApplicationController` to audit all controller actions:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include ActionAudit
+
+  # All controllers inheriting from this will be audited
+end
+```
+
+### Selective Auditing
+
+Include ActionAudit only in specific controllers:
+
+```ruby
+class Admin::UsersController < ApplicationController
+  include ActionAudit  # Only admin actions are audited
+end
+
+class PublicController < ApplicationController
+  # No auditing for public actions
+end
+```
+
+### Namespaced Controllers
+
+ActionAudit automatically handles namespaced controllers:
+
+```ruby
+class Admin::Users::ProfilesController < ApplicationController
+  include ActionAudit
+
+  def update
+    # Will look up: admin/users/profiles/update in audit.yml
+  end
+end
+```
+
+## Common Usage Patterns
+
+### User Management
+
+```yaml
+# config/audit.yml
+admin:
+  users:
+    create: "Admin created user %{email} with role %{role}"
+    update: "Admin updated user %{id}"
+    destroy: "Admin deleted user %{id}"
+    activate: "Admin activated user %{id}"
+    deactivate: "Admin deactivated user %{id}"
+```
+
+```ruby
+class Admin::UsersController < ApplicationController
+  include ActionAudit
+
+  def create
+    @user = User.create!(user_params)
+    # Logs: "Admin created user john@example.com with role editor"
+  end
+
+  def activate
+    @user = User.find(params[:id])
+    @user.update!(active: true)
+    # Logs: "Admin activated user 123"
+  end
+end
+```
+
+### Authentication & Sessions
+
+```yaml
+# config/audit.yml
+sessions:
+  create: "User logged in with %{email}"
+  destroy: "User logged out"
+
+passwords:
+  create: "Password reset requested for %{email}"
+  update: "Password changed for user %{user_id}"
+```
+
+```ruby
+class SessionsController < ApplicationController
+  include ActionAudit
+
+  def create
+    # params[:email] = "user@example.com"
+    # Logs: "User logged in with user@example.com"
+  end
+
+  def destroy
+    # Logs: "User logged out"
+  end
+end
+```
+
+### API Endpoints
+
+```yaml
+# config/audit.yml
+api:
+  v1:
+    webhooks:
+      create: "Webhook received from %{source} with %{event_type}"
+
+    users:
+      create: "API user created via client %{client_id}"
+      update: "API user %{id} updated via client %{client_id}"
+```
+
+```ruby
+class API::V1::WebhooksController < ApplicationController
+  include ActionAudit
+
+  def create
+    # params = { source: "stripe", event_type: "payment.succeeded" }
+    # Logs: "Webhook received from stripe with payment.succeeded"
+  end
+end
+```
+
+### Content Management
+
+```yaml
+# config/audit.yml
+posts:
+  create: "Created post '%{title}'"
+  update: "Updated post %{id}"
+  destroy: "Deleted post '%{title}'"
+  publish: "Published post '%{title}'"
+  unpublish: "Unpublished post '%{title}'"
+
+categories:
+  create: "Created category '%{name}'"
+  update: "Updated category %{id} to '%{name}'"
+  destroy: "Deleted category '%{name}'"
+```
+
+## Advanced Usage
+
+### Custom Parameter Extraction
+
+Sometimes you need to log information that's not directly in `params`. You can modify parameters before the audit:
+
+```ruby
+class PostsController < ApplicationController
+  include ActionAudit
+
+  before_action :set_audit_params, only: [:publish, :unpublish]
+
+  def publish
+    @post = Post.find(params[:id])
+    @post.update!(published: true)
+    # Will use the custom title parameter we set
+  end
+
+  private
+
+  def set_audit_params
+    @post = Post.find(params[:id])
+    params[:title] = @post.title  # Add title to params for auditing
+  end
+end
+```
+
+### Conditional Auditing
+
+You can conditionally include ActionAudit or skip certain actions:
+
+```ruby
+class UsersController < ApplicationController
+  include ActionAudit
+
+  # Skip auditing for certain actions
+  skip_after_action :audit_request, only: [:show, :index]
+
+  # Or use conditional logic
+  def sensitive_action
+    # Custom auditing logic here if needed
+  end
+end
+```
+
+### Integration with Current User
+
+ActionAudit works well with authentication systems. The custom formatter can access `current_user`:
+
+```ruby
+# config/initializers/action_audit.rb
+ActionAudit.log_formatter = lambda do |controller, action, message|
+  if defined?(current_user) && current_user
+    "#{message} (by #{current_user.email})"
+  else
+    "#{message} (by anonymous user)"
+  end
+end
+```
+
+## Testing
+
+### Testing Audit Messages
+
+You can test that audit messages are being logged correctly:
+
+```ruby
+# spec/controllers/users_controller_spec.rb
+RSpec.describe UsersController, type: :controller do
+  describe "#create" do
+    it "logs user creation" do
+      expect(Rails.logger).to receive(:info).with(/Created user.*john@example\.com/)
+
+      post :create, params: { user: { email: "john@example.com" } }
+    end
+  end
+end
+```
+
+### Testing Without Auditing
+
+In tests where you don't want audit logging, you can stub it:
+
+```ruby
+before do
+  allow(controller).to receive(:audit_request)
+end
+```
+
+## Performance Considerations
+
+ActionAudit is designed to be lightweight:
+
+- **Minimal Overhead**: Only runs after successful actions
+- **Lazy Loading**: Audit messages are loaded once at startup
+- **No Database Calls**: All auditing happens through Rails logger
+- **Graceful Failures**: Missing messages or parameters won't break your application
+
+## Error Handling
+
+ActionAudit handles errors gracefully:
+
+1. **Missing Messages**: If no audit message is configured for an action, nothing is logged
+2. **Missing Parameters**: If interpolation fails, the error is logged alongside the original message
+3. **Invalid YAML**: Rails will warn about YAML syntax errors during loading
+
+## Next Steps
+
+- [Learn about multi-engine setup](multi-engine.md)
+- [See real-world examples](examples.md)
+- [Check the API reference](api-reference.md)

data/lib/action-audit.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "action_audit"

data/lib/action_audit/audit_messages.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module ActionAudit
+  class AuditMessages
+    class << self
+      def messages
+        @messages ||= {}
+      end
+
+      def load_from_file(file_path)
+        return unless File.exist?(file_path)
+
+        content = YAML.load_file(file_path)
+        return unless content.is_a?(Hash)
+
+        messages.deep_merge!(content)
+      end
+
+      def load_from_engines
+        # Load from all Rails engines and the main app
+        if defined?(Rails) && Rails.application
+          # Load from main application
+          main_audit_file = Rails.root.join("config", "audit.yml")
+          load_from_file(main_audit_file) if File.exist?(main_audit_file)
+
+          # Load from all engines
+          Rails.application.railties.each do |railtie|
+            next unless railtie.respond_to?(:root)
+
+            engine_audit_file = railtie.root.join("config", "audit.yml")
+            load_from_file(engine_audit_file) if File.exist?(engine_audit_file)
+          end
+        end
+      end
+
+      def lookup(controller_path, action_name)
+        # Convert controller path to nested hash lookup
+        # e.g., "manage/accounts" becomes ["manage", "accounts"]
+        path_parts = controller_path.split("/")
+
+        # Navigate through nested hash structure
+        current_level = messages
+        path_parts.each do |part|
+          current_level = current_level[part]
+          return nil unless current_level.is_a?(Hash)
+        end
+
+        # Look up the action
+        current_level[action_name]
+      end
+
+      def clear!
+        @messages = {}
+      end
+
+      def add_message(controller_path, action_name, message)
+        path_parts = controller_path.split("/")
+
+        # Navigate/create nested structure
+        current_level = messages
+        path_parts.each do |part|
+          current_level[part] ||= {}
+          current_level = current_level[part]
+        end
+
+        # Set the message
+        current_level[action_name] = message
+      end
+    end
+  end
+end

data/lib/action_audit/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActionAudit
+  class Engine < ::Rails::Engine
+    isolate_namespace ActionAudit
+
+    initializer "action_audit.load_audit_messages", after: :load_config_initializers do
+      ActionAudit::AuditMessages.load_from_engines
+    end
+
+    # Reload audit messages in development when files change
+    config.to_prepare do
+      if Rails.env.development?
+        ActionAudit::AuditMessages.clear!
+        ActionAudit::AuditMessages.load_from_engines
+      end
+    end
+  end
+end

data/lib/action_audit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActionAudit
+  VERSION = "1.0.1"
+end

data/lib/action_audit.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/concern"
+require "rails"
+
+require_relative "action_audit/version"
+require_relative "action_audit/audit_messages"
+require_relative "action_audit/engine" if defined?(Rails)
+
+module ActionAudit
+  class Error < StandardError; end
+
+  # Configuration attributes
+  mattr_accessor :log_formatter, default: nil
+  mattr_accessor :log_tag, default: nil
+
+  extend ActiveSupport::Concern
+
+  included do
+    after_action :audit_request
+  end
+
+  private
+
+  def audit_request
+    controller_path = self.class.name.underscore.gsub("_controller", "")
+    action_name = action_name()
+
+    # Look up the audit message
+    message = ActionAudit::AuditMessages.lookup(controller_path, action_name)
+    return unless message
+
+    # Interpolate the message with params
+    interpolated_message = interpolate_message(message, params)
+
+    # Format the log entry
+    formatted_message = if ActionAudit.log_formatter
+      ActionAudit.log_formatter.call(controller_path, action_name, interpolated_message, params)
+    else
+      "#{controller_path}/#{action_name} - #{interpolated_message}"
+    end
+
+    # Log with optional tag
+    if ActionAudit.log_tag
+      Rails.logger.tagged(ActionAudit.log_tag) do
+        Rails.logger.info(formatted_message)
+      end
+    else
+      Rails.logger.info(formatted_message)
+    end
+  end
+
+  def interpolate_message(message, interpolation_params)
+    return "" if message.nil?
+    return message.to_s unless message.respond_to?(:%)
+
+    # Convert params to hash with symbol keys for interpolation
+    unsafe_hash = interpolation_params.to_unsafe_h
+    string_params = unsafe_hash.respond_to?(:deep_stringify_keys) ? unsafe_hash.deep_stringify_keys : unsafe_hash
+
+    # Convert to symbol keys for string interpolation
+    symbol_params = {}
+    string_params.each { |k, v| symbol_params[k.to_sym] = v }
+
+    # Perform string interpolation
+    message % symbol_params
+  rescue KeyError => e
+    # If interpolation fails, log the original message with error info
+    "#{message} (interpolation error: #{e.message})"
+  rescue TypeError
+    # If message is not a string or doesn't support %, return as-is
+    message.to_s
+  end
+end

data/lib/generators/action_audit/install_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module ActionAudit
+  class InstallGenerator < Rails::Generators::Base
+    desc "Install ActionAudit configuration"
+
+    def self.source_root
+      @source_root ||= File.expand_path("templates", __dir__)
+    end
+
+    def copy_audit_config
+      template "audit.yml", "config/audit.yml"
+    end
+
+    def create_initializer
+      template "action_audit.rb", "config/initializers/action_audit.rb"
+    end
+
+    def show_readme
+      readme "README"
+    end
+  end
+end

data/lib/generators/action_audit/templates/README

@@ -0,0 +1,25 @@
+===============================================================================
+
+ActionAudit has been installed!
+
+Next steps:
+
+1. Include ActionAudit in your controllers:
+
+   class ApplicationController < ActionController::Base
+     include ActionAudit
+   end
+
+   Or include it in specific controllers:
+
+   class Admin::UsersController < ApplicationController
+     include ActionAudit
+   end
+
+2. Edit config/audit.yml to define your audit messages
+
+3. Customize logging in config/initializers/action_audit.rb (optional)
+
+4. Test your setup by triggering a controller action and checking your logs
+
+===============================================================================

data/lib/generators/action_audit/templates/action_audit.rb

@@ -0,0 +1,17 @@
+# ActionAudit configuration
+# Customize how audit logs are formatted and tagged
+
+# Add a tag to all audit log entries
+# ActionAudit.log_tag = "AUDIT"
+
+# Customize the log message format
+# The formatter receives (controller_path, action_name, interpolated_message)
+# ActionAudit.log_formatter = lambda do |controller, action, message|
+#   user_info = defined?(current_user) && current_user ? "User: #{current_user.email}" : "User: anonymous"
+#   "[#{Time.current.iso8601}] #{controller}/#{action} | #{message} | #{user_info}"
+# end
+
+# Simple formatter example:
+# ActionAudit.log_formatter = ->(controller, action, msg) do
+#   "AUDIT: #{controller}/#{action} - #{msg}"
+# end

data/lib/generators/action_audit/templates/audit.yml

@@ -0,0 +1,30 @@
+# ActionAudit configuration file
+# This file defines audit messages for your controllers
+# Organize by controller namespace and action
+
+# Example structure:
+# namespace:
+#   controller:
+#     action: "Message with %{param} interpolation"
+
+# Example audit messages
+# Uncomment and customize as needed
+
+# admin:
+#   users:
+#     create: "Created user %{email}"
+#     update: "Updated user %{id}"
+#     destroy: "Deleted user %{id}"
+#   accounts:
+#     create: "Created account %{name}"
+#     update: "Updated account %{id}"
+
+# sessions:
+#   create: "User logged in with %{email}"
+#   destroy: "User logged out"
+
+# posts:
+#   create: "Created post '%{title}'"
+#   update: "Updated post %{id}"
+#   publish: "Published post %{id}"
+#   unpublish: "Unpublished post %{id}"

data/sig/action_audit.rbs

@@ -0,0 +1,4 @@
+module ActionAudit
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end