mongoid-auditor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 869c768a48b7fb7e52b1d437b89b484f72cc397dd74b0416c229088c6967189e
+  data.tar.gz: e1b3f3f5c59eb810af348dad24268b6b06fa1dbe2874c9c631b4d15a19463908
+SHA512:
+  metadata.gz: 0200e27d63508fb92aabc155a487497720e0657de998b3ae15ec41f787aed92d94e02bbfcd0ba9ed5d62e3603f8ab37652ab45053eb17a759e84a97843abbffa
+  data.tar.gz: e4c4d32d87f3b4f07b68dac2caad98aceb2bab67dcdd461328b35ea52730155f97c5defd341b41fcc2698ffcde0692000cf634dda24bdfcadd27e89686c6dcd7

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-24
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The License
+
+Copyright (c) 2025 Pralad Mishra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,272 @@
+# Mongoid::Auditor
+
+Mongoid::Auditor is a Rails engine that provides automatic auditing for Mongoid models, controllers, and background jobs. It tracks changes, errors, and events in your application using a structured `AuditLog` model and is recorded asynchronously using a background job called `AuditorJob`.
+
+## Features
+
+* Automatic auditing of Mongoid model changes (`create`, `update`, `destroy`).
+* Error logging for controllers and background jobs.
+* Asynchronous audit logging with `AuditorJob`.
+* Configurable auditing for models and controllers.
+* Compatible with Rails 7+ and Mongoid 7+.
+
+## Installation
+
+Add this in your Gemfile:
+
+```ruby
+gem 'mongoid-auditor', path: '../gems/mongoid-auditor' # adjust path if using a local gem
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install mongoid-auditor
+```
+
+## Setup
+
+Generate the initializer with the Rails generator:
+
+```bash
+rails generate mongoid:auditor:install
+```
+
+This creates `config/initializers/mongoid_auditor.rb` with default configuration:
+
+```ruby
+Mongoid::Auditor.configure do |config|
+  config.enabled = true
+  config.log_models = true  # logs the changes made to the model
+  config.log_controllers = true  # logs the errors
+end
+```
+
+## Usage
+
+### Models
+
+Include the `Auditable` concern in your Mongoid models to log create, update, and destroy events automatically:
+
+```ruby
+class Product
+  include Mongoid::Document
+  include Mongoid::Auditor::Auditable
+end
+```
+
+Or add this to the `ApplicationDocument` module to apply it to all models:
+
+```ruby
+module ApplicationDocument
+  extend ActiveSupport::Concern
+
+  included do
+    include Mongoid::Auditor::Auditable
+  end
+end
+```
+
+This ensures that all mutations to models are automatically recorded in `AuditLog`.
+
+**Note:** GET requests are not recorded. If a POST behaves like a GET, add this to your controller:
+
+```ruby
+skip_before_action :init_audit_log, only: %i[your_method_name_here]
+```
+***Note:** if you want to skip specific jobs from being logged add this in specific job file:
+
+```ruby
+class BackgroundJob < ApplicationJob
+  queue_as :default
+
+  self.skip_audit = true
+end
+```
+
+
+### Controllers
+
+Include the `InitAuditLog` concern to initialize the RequestStore to store basic information about the request.
+Include the `AuditControllerErrorLog` concern to log controller errors.
+
+```ruby
+class ProductsController < ApplicationController
+  include Mongoid::Auditor::InitAuditLog
+  include Mongoid::Auditor::AuditControllerErrorLog
+end
+```
+
+### Jobs
+
+Include the `InitJobAuditLog` concern and `audit_skip` class attribute in your `ApplicationJob` to audit background jobs:
+
+```ruby
+class ApplicationJob < ActiveJob::Base
+  include Mongoid::Auditor::InitJobAuditLog
+  class_attribute :skip_audit, default: false
+end
+```
+
+Jobs automatically track `request_id`, `actor`, API endpoint, and parameters.
+
+### Testing Instances
+During testing, the number of AuditorJob records can grow significantly depending on the number of calls and background operations.
+It is therefore recommended to disable the auditor in test environments.
+```ruby
+# config/initializers/mongoid_auditor.rb
+
+Mongoid::Auditor.configure do |config|
+  # Disable auditor in test environment to avoid excessive job creation
+  config.enabled = !Rails.env.test?
+end
+
+```
+
+### AuditLog Model
+
+The `Mongoid::Auditor::AuditLog` model stores audit entries with the following attributes:
+
+* `request_id` — Request or job ID.
+* `actor` — User or background job (e.g., `AuditorJob`).
+* `path` — Controller action or job name.
+* `model_type` — Class of the audited model (e.g., `Product`).
+* `model_id` — ID of the audited model.
+* `event` — `create`, `update`, `destroy`, or `error`.
+* `dirties` — Before/after attribute snapshots (hash with `attribute: [before_value, after_value]` format).
+* `sequence` — Incremental sequence number for ordering events within a request.
+* `error` — Contains class, message and backtrace of the error (when `has_error` is true).
+
+Logs are written asynchronously by `Mongoid::Auditor::AuditorJob` to minimize performance impact.
+
+### RequestContext Model
+
+The `Mongoid::Auditor::RequestContext` model stores context information for requests and background jobs, providing a reference for audit logging.
+
+**Attributes:**
+
+* `job_id` — ID of the background job (e.g., `AuditorJob`), if applicable.
+* `request_id` — Unique ID representing the request or job context.
+
+**Indexes:**
+
+* `job_id` — Unique index to ensure one context per job.
+* `request_id` — Standard index to optimize lookups by request.
+
+**Usage:**  
+`RequestContext` allows the auditor to link audit logs to a specific request or background job, making it easier to 
+trace changes and errors back to the original operation.
+
+**NOTE:** The `RequestContext` data is automatically deleted after 24 hours (via TTL index) and also cleaned up when jobs complete to prevent unbounded growth and minimize database usage. This ensures the audit system remains efficient and does not consume unnecessary space.
+---
+
+### Mongoid::Auditor::Current
+
+`Mongoid::Auditor::Current` is a `CurrentAttributes` singleton that keeps request-specific audit state in memory. It provides a thread-safe way to store and access audit-related data during a request or job execution.
+
+**Attributes:**
+
+* `request_id` — Current request or job ID for the audit.
+* `actor_id` — ID of the user or system performing the action.
+* `path` — Controller action name or job name being executed.
+* `request_params` — Parameters of the current request.
+* `audit_logs` — Collection of `AuditLog` entries accumulated during the request.
+* `audit_sequence` — Incremental sequence number used to order audit events for the current request.
+
+**Usage:**  
+`Mongoid::Auditor::Current` ensures that every audit event created during a request or background job has consistent context. For example, `AuditLog` entries can reference `Current.request_id` and `Current.actor_id` to maintain traceability across all operations within that request.
+
+### Example Audit Workflow
+
+**Creating a Product:**
+
+```ruby
+product = Product.create(name: "Laptop", price: 999.99)
+```
+
+`AuditorJob` creates an `AuditLog` entry:
+
+```ruby
+{
+  request_id: "req-456",
+  actor: "",
+  path: "POST api/v1/products/create",
+  model_type: "Product",
+  model_id: '68d95bc84cf7bc8798179ebd',
+  event: "create",
+  dirties: { name: [nil, "Laptop"], price: [nil, 999.99] },
+  sequence: 1,
+  has_error: false,
+  error: nil
+}
+```
+
+**Updating a Product:**
+
+```ruby
+product.update(price: 1099.99)
+```
+
+`AuditorJob` logs:
+
+```ruby
+{
+  request_id: "req-457",
+  actor: "user@example.com",
+  path: "PUT api/v1/products/#{product.id}",
+  model_type: "Product",
+  model_id: product.id.to_s,
+  event: "update",
+  dirties: { price: [999.99, 1099.99] },
+  sequence: 2,
+  has_error: false,
+  error: nil
+}
+```
+
+**Controller Error:**
+If a validation fails in `ProductsController`:
+
+```ruby
+{
+  request_id: "req-458",
+  actor: "user@example.com",
+  path: "PUT api/v1/products/123",
+  model_type: "Product",
+  model_id: "123",
+  event: "update",
+  has_error: true,
+  dirties: {},
+  sequence: 3,
+  error: {
+    class: "ActiveRecord::RecordInvalid",
+    message: "Validation failed: Name can't be blank",
+    backtrace: ["..."]
+  }
+}
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt.
+
+To install this gem locally, run `bundle exec rake install`. To release a new version, update the version in `version.rb`, then run `bundle exec rake release` to create a git tag, push commits, and release to [RubyGems](https://rubygems.org).
+
+## Troubleshooting
+
+* **Performance Concerns:** `Mongoid::Auditor::AuditorJob` processes logs asynchronously. Disable auditing for high-traffic endpoints using `skip_before_action` or `skip_audit_for`.
+* **Large Audit Logs:** Use Mongoid's query capabilities to filter or archive old `AuditLog` entries. Consider adding TTL indexes for automatic cleanup.
+* **Missing Logs:** Ensure `config.enabled` is true and relevant concerns are included. Check that `Current.path` is set (it's nil for GET requests by default).
+* **Database Indexes:** The gem includes indexes on commonly queried fields (`request_id`, `model_type`, `model_id`, `actor`, `has_error`, `created_at`) for optimal query performance.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/[USERNAME]/mongoid-auditor](https://github.com/[USERNAME]/mongoid-auditor). Please follow the [code of conduct](https://github.com/[USERNAME]/mongoid-auditor/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Mongoid::Auditor project is expected to follow the [code of conduct](https://github.com/[USERNAME]/mongoid-auditor/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/mongoid/auditor/audit.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Auditor
+    class Audit
+      class << self
+        def log(entry)
+          return unless entry.is_a?(Hash)
+
+          ::Mongoid::Auditor::AuditLog.create!(entry)
+        rescue StandardError => e
+          logger&.error("Auditor::Audit.log failed: #{e.class} #{e.message}\n#{e.backtrace&.take(5)&.join("\n")}")
+          log_error(e, entry)
+        end
+
+        def logger
+          defined?(Rails) ? Rails.logger : nil
+        end
+
+        private
+
+        def log_error(err, entry)
+          ::Mongoid::Auditor::AuditLog.create!(
+            request_id: entry[:request_id],
+            actor: entry[:actor],
+            path: entry[:path],
+            params: entry[:params],
+            model_type: entry[:model_type],
+            model_id: entry[:model_id],
+            has_error: true,
+            event: entry[:event] || 'error',
+            dirties: entry[:dirties] || {},
+            sequence: entry[:sequence],
+            error: error_data(err)
+          )
+        rescue StandardError => e
+          logger&.error("Auditor::Audit.log failed to persist error: #{e.class} #{e.message}\n#{e.backtrace&.take(5)&.join("\n")}")
+        end
+
+        def error_data(err)
+          if err.is_a?(StandardError)
+            { class: err.class.to_s, message: err.message, backtrace: err.backtrace&.take(10) }
+          elsif err.is_a?(Hash)
+            { class: err[:class] || err['class'], message: err[:message] || err['message'], backtrace: err[:backtrace] || err['backtrace'] }
+          else
+            { class: err.class.to_s, message: err.to_s, backtrace: nil }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/auditor/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Auditor
+    class Configuration
+      attr_accessor :enabled, :log_models, :log_controllers, :queue_name, :skip_password_fields
+
+      def initialize
+        @enabled = true
+        @log_models = true
+        @log_controllers = true
+        @queue_name = :default
+        @skip_password_fields = %w[password password_confirmation token secret api_key]
+      end
+
+      # Helper method to check if auditing should be skipped for a specific environment
+      def enabled_for_environment?
+        return false unless enabled
+
+        # Skip in test environment by default unless explicitly enabled
+        return false if defined?(Rails) && Rails.env.test? && enabled == true
+
+        enabled
+      end
+    end
+  end
+end

data/lib/mongoid/auditor/generators/install_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Mongoid
+  module Auditor
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        source_root File.expand_path('templates', __dir__)
+        desc 'Creates a Mongoid Auditor initializer in your Rails application.'
+
+        def copy_initializer
+          template 'mongoid_auditor_initializer.rb', 'config/initializers/mongoid_auditor.rb'
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/auditor/generators/templates/mongoid_auditor_initializer.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+Mongoid::Auditor.configure do |config|
+  # Enable or disable auditing
+  config.enabled = true
+
+  # Enable model auditing
+  config.log_models = true
+
+  # Enable controller auditing
+  config.log_controllers = true
+end

data/lib/mongoid/auditor/helpers/controller_helpers/audit_controller_error_log.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Auditor
+    module AuditControllerErrorLog
+      extend ActiveSupport::Concern
+
+      included do
+        around_action :audit_exceptions
+      end
+
+      private
+
+      def audit_exceptions
+        yield
+      rescue StandardError => e
+        audit_error(e)
+        raise
+      end
+
+      def audit_error(exception)
+        return unless ::Mongoid::Auditor.config.enabled && ::Mongoid::Auditor.config.log_controllers
+
+        data = build_entry(exception)
+        ::Mongoid::Auditor::AuditorJob.perform_later(:controller, data[:error], data[:entry])
+      rescue StandardError => e
+        Rails.logger&.error("AuditLogger failed to log error: #{e.class} #{e.message}\n#{e.backtrace&.take(5)&.join("\n")}")
+      end
+
+      def build_entry(exception)
+        model_name = model_context_from_params(request.params)
+        {
+          entry: {
+            request_id: request&.request_id,
+            actor: current_user&.id&.to_s,
+            path: "#{request.method} #{request.fullpath}",
+            params: filter_sensitive_params(request.filtered_parameters.except(:controller, :action)),
+            model_type: model_name,
+            model_id: request.params[:id],
+            has_error: true,
+            event: request.params[:action],
+            dirties: {},
+            sequence: ::Mongoid::Auditor::Current.audit_sequence.to_i + 1
+          },
+          error: {
+            class: exception.class.to_s,
+            message: exception.message,
+            backtrace: exception.backtrace&.take(5)
+          }
+        }
+      end
+
+      def model_context_from_params(params)
+        extract_model_type(params) || fallback_model_type(params[:controller])
+      end
+
+      def extract_model_type(params)
+        params.keys
+              .reject { |k| k.in?(%w[controller action id]) || k.end_with?('_id') }
+              .first
+              &.singularize
+              &.camelize
+      end
+
+      def fallback_model_type(controller_name)
+        controller_name.split('/').last.singularize.camelize
+      end
+
+      def filter_sensitive_params(params)
+        skip_fields = ::Mongoid::Auditor.config.skip_password_fields || []
+        params.except(*skip_fields)
+      end
+    end
+  end
+end

data/lib/mongoid/auditor/helpers/controller_helpers/controller_audit_helper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Auditor
+    module ControllerAuditHelper
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def skip_audit_for(*actions)
+          skip_before_action :init_audit_store, only: actions
+          before_action :set_skip_audit_flag, only: actions
+        end
+      end
+
+      private
+
+      def set_skip_audit_flag
+        ::Mongoid::Auditor::Current.path = nil
+      end
+    end
+  end
+end