model_timeline 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7406b06646ef46c0b8d2541835ebeaa5e0f71638c600d0b7de45903bb36b2c81
+  data.tar.gz: dad655ebda19102a5e09eb3a51d07ac15cfbca051527ee3c3a71d979ab2a4543
+SHA512:
+  metadata.gz: 4f618bea0cc20328d5d2a61352c753ec39fbe04f90b7f909ba93df236ab28a4e239515c3b0b70913381149e99996c189ebb41afe5e2a2d6649e3fdb0fabf24b4
+  data.tar.gz: d145d2798077f4bbb13191f966d8b73433330e5360b808862f14ddc3f1e4d7e6d97d231ad9e0828a5f63f4f759453550eb5cb132781a9a5dfa15b21b816ec36b

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexandre Stapenhorst
+
+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,453 @@
+# ModelTimeline
+
+ModelTimeline is a flexible audit logging gem for Rails applications that allows you to track changes to your models with comprehensive attribution and flexible configuration options.
+
+## How this gem is different than paper_trail and audited?
+
+ModelTimeline was designed with several unique features that differentiate it from other auditing gems:
+
+- *Multiple configurations per model:* Unlike paper_trail and audited, ModelTimeline allows you to define multiple timeline configurations on the same model. This means you can track different sets of attributes for different purposes.
+- *Targeted tracking:* Configure separate timelines for different aspects of your model (e.g., one for security events, another for content changes).
+- PostgreSQL optimization: Built to leverage PostgreSQL's JSONB capabilities for efficient storage and advanced querying.
+- *IP address tracking:* Automatically captures the client IP address for each change.
+- *Rich metadata support:* Add custom metadata to timeline entries via configuration or at runtime.
+- *Flexible user attribution:* Works with any authentication system by using a configurable method to retrieve the current user.
+- *Comprehensive RSpec support:* Built-in matchers for testing timeline recording.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```sh
+gem 'model_timeline'
+```
+
+And then execute:
+
+```sh
+$ bundle install
+```
+
+Or install it yourself as:
+
+```sh
+$ gem install model_timeline
+```
+
+Run the generator to create the necessary migration:
+
+```sh
+$ rails generate model_timeline:install
+$ rails db:migrate
+```
+
+For a custom table name:
+
+```sh
+$ rails generate model_timeline:install --table_name=custom_timeline_entries
+$ rails db:migrate
+```
+## Configuration
+
+### Initializer
+
+Configure the gem in an initializer:
+
+```ruby
+# config/initializers/model_timeline.rb
+ModelTimeline.configure do |config|
+  # Method to retrieve the current user in controllers (default: :current_user)
+  config.current_user_method = :current_user
+
+  # Method to retrieve the client IP address in controllers (default: :remote_ip)
+  config.current_ip_method = :remote_ip
+
+  # Enable/disable timeline tracking globally
+  # config.enabled = true # Enabled by default
+end
+```
+
+### Model Configuration
+Include the Timelineable module in your models (this happens automatically with Rails):
+
+> **Important**: When defining multiple timelines on the same model, each must use a unique `class_name` option. Otherwise, the associations will conflict and an error will be raised.
+
+```ruby
+# Basic usage with default settings
+class User < ApplicationRecord
+  has_timeline
+end
+
+# Using a custom association name with class_name along default
+class User < ApplicationRecord
+  has_timeline
+
+  has_timeline :security_events, class_name: 'SecurityTimelineEntry'
+end
+
+# Tracking only specific attributes
+class User < ApplicationRecord
+  has_timeline only: [:last_login_at, :login_count, :status],
+               class_name: 'LoginTimelineEntry'
+end
+
+# Ignoring specific attributes
+class User < ApplicationRecord
+  has_timeline :profile_changes,
+               ignore: [:password, :remember_token, :login_count],
+               class_name: 'ProfileTimelineEntry'
+end
+
+# Tracking only specific events
+class User < ApplicationRecord
+  has_timeline :content_changes,
+               on: [:update, :destroy],
+               class_name: 'ContentTimelineEntry'
+end
+
+# Using a custom timeline entry class and table
+class User < ApplicationRecord
+  has_timeline :custom_timeline_entries,
+               class_name: 'CustomTimelineEntry'
+end
+
+# Adding additional metadata to each entry
+class Order < ApplicationRecord
+  has_timeline :admin_changes,
+               class_name: 'AdminTimelineEntry',
+               meta: {
+                 app_version: "1.0",
+                 # Dynamic values using methods or procs
+                 section: :section_name,
+                 category_id: ->(record) { record.category_id }
+               }
+end
+```
+
+### Using Metadata
+
+<!-- ! THIS IS WRONG, NEEDS TO BE UPDATED.  -->
+ModelTimeline allows you to include custom metadata with your timeline entries, which is especially useful for tracking changes across related entities or adding domain-specific context.
+
+#### Adding Metadata Through Configuration
+
+When defining a timeline, any fields you include in the `meta` option will be evaluated and stored in the timeline entry:
+
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :post
+
+  has_timeline :comment_changes,
+               class_name: 'ContentTimelineEntry',
+               meta: {
+                 post_id: ->(record) { record.post_id },
+               }
+end
+```
+
+If your timeline table has columns that match the keys in your `meta` hash, these values will be stored in
+those dedicated columns. Otherwise they will be ignored. (This might change in the future and a metadata column might be
+added to put additional metadata that doesn't have a dedicated column.)
+
+#### Adding Metadata at Runtime
+
+```ruby
+# Add metadata for a specific operation
+ModelTimeline.with_metadata(post_id: '123456') do
+  comment.update(body: 'Updated comment')
+end
+
+# Add metadata for the current thread/request
+ModelTimeline.metadata = { post_id: '123456' }
+comment.update(status: 'approved')
+```
+
+#### Custom Timeline Tables with Domain-specific Columns
+
+For tracking related entities more effectively, you can create a custom timeline table with additional columns:
+
+```ruby
+# Migration to create a product-specific timeline table
+class CreatePostTimelineEntries < ActiveRecord::Migration[6.1]
+  def change
+    create_table :post_timeline_entries do |t|
+      # Standard ModelTimeline columns
+      t.string   :timelineable_type
+      t.integer  :timelineable_id
+      t.string   :action
+      t.jsonb    :object_changes
+      t.integer  :user_id
+      t.string   :ip_address
+
+      # Custom columns that can be populated via the meta option
+      t.integer  :post_id
+
+      t.timestamps
+    end
+
+    add_index :post_timeline_entries, [:timelineable_type, :timelineable_id]
+    add_index :post_timeline_entries, :post_id
+    add_index :post_timeline_entries, :user_id
+  end
+end
+```
+
+Then, use this table with your models:
+
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :post
+
+  has_timeline :product_changes,
+               class_name: 'PostTimelineEntry',
+               meta: {
+                 post_id: ->(record) { record.post_id },
+                 #  OR
+                 # post_id: :post_id
+                 #  OR
+                 # post_id: :my_custom_post_id_method
+               }
+end
+```
+
+With this approach, you can easily query all changes related to a specific post or product:
+
+```ruby
+# Find all timeline entries for a specific post
+PostTimelineEntry.where(post_id: post.id)
+```
+
+This makes it significantly easier to track and analyze changes across related models within a specific domain context.
+
+### Controller Integration
+
+Define the current user and ip_address for the current request
+
+```ruby
+class ApplicationController < ActionController::Base
+  private
+
+    # ModelTimeline will look for the methods set in the initializer.
+    # Given
+    #  ModelTimeline.configure do |config|
+    #   config.current_user_method = :my_current_user
+    #   config.current_ip_method = :remote_ip
+    # end
+    #
+    def my_current_user
+      my_current_user_instance
+    end
+
+    def remote_ip
+      request.remote_ip
+    end
+end
+```
+
+## Usage
+
+### Basic Usage
+
+Once configured, ModelTimeline automatically tracks changes to your models:
+
+```ruby
+user = User.create(username: 'johndoe', email: 'john@example.com')
+# Creates a timeline entry with action: 'create'
+
+user.update(email: 'new@example.com')
+# Creates a timeline entry with action: 'update' and the changed attributes
+
+user.destroy
+# Creates a timeline entry with action: 'destroy'
+```
+
+### Accessing Timeline Entries
+
+
+```ruby
+# Get all timeline entries for a model
+user.timeline_entries
+
+# Get timeline entries with a specific action
+user.timeline_entries.where(action: 'update')
+
+# Find entries for a specific user
+ModelTimeline::TimelineEntry.for_user(admin)
+
+# Find entries from a specific IP
+ModelTimeline::TimelineEntry.for_ip_address('192.168.1.1')
+```
+
+### Custom Tables and Models
+
+```ruby
+# Create a custom timeline entry class
+class SecurityTimelineEntry < ModelTimeline::TimelineEntry
+  self.table_name = 'security_timeline_entries'
+
+  # Add custom scopes or methods
+  scope :critical, -> { where("object_changes::text ILIKE '%password%'") }
+end
+
+# Use it in your model
+class User < ApplicationRecord
+  has_timeline :security_timelines,
+               class_name: 'SecurityTimelineEntry',
+               only: [:sign_in_count, :last_sign_in_at, :role]
+end
+
+# Access the custom timeline
+user.security_timelines
+```
+
+### Controlling Timeline Recording
+
+Temporarily enable or disable timeline recording:
+
+```ruby
+# Disable timeline recording for a block of code
+ModelTimeline.without_timeline do
+  # Changes made here won't be recorded
+  user.update(name: 'New Name')
+  post.destroy
+end
+
+# Set custom context for timeline entries
+ModelTimeline.with_timeline(current_user: admin_user, current_ip: '10.0.0.1', metadata: { reason: 'Admin action' }) do
+  # Changes made here will be attributed to admin_user from 10.0.0.1
+  # with the additional metadata
+  user.update(status: 'suspended')
+end
+```
+
+Add additional contextual information to timeline entries:
+
+```ruby
+# Set metadata for all timeline entries in the current request
+ModelTimeline.metadata = { import_batch: 'daily_sync_2023_01_01' }
+
+# Temporarily add or override metadata for a block
+ModelTimeline.with_metadata(source: 'api') do
+  # All timeline entries created here will include this metadata
+  user.update(status: 'active')
+end
+```
+
+### Timeline Entry Scopes
+
+ModelTimeline provides several useful scopes for querying timeline entries:
+
+```ruby
+# Find entries for a specific model
+ModelTimeline::TimelineEntry.for_timelineable(user)
+
+# Find entries created by a specific user
+ModelTimeline::TimelineEntry.for_user(admin)
+
+# Find entries from a specific IP address
+ModelTimeline::TimelineEntry.for_ip_address('192.168.1.1')
+
+# Find entries where a specific attribute was changed
+ModelTimeline::TimelineEntry.with_changed_attribute('email')
+
+# Find entries where an attribute was changed to a specific value
+ModelTimeline::TimelineEntry.with_changed_value('status', 'active')
+```
+
+### PostgreSQL-Specific Features
+
+ModelTimeline leverages PostgreSQL's JSONB capabilities for efficient querying:
+
+```ruby
+# Find timeline entries containing specific changes using JSONB containment
+TimelineEntry.where("object_changes @> ?", {email: ["old@example.com", "new@example.com"]}.to_json)
+
+# Search for any value in the changes
+TimelineEntry.where("object_changes::text LIKE ?", "%specific_value%")
+```
+
+The gem creates GIN indexes on the JSONB columns for optimized performance with large audit logs.
+
+
+## RSpec Integration
+
+### Configuration
+
+Configure RSpec to work with ModelTimeline:
+
+```ruby
+# spec/support/model_timeline.rb
+require 'model_timeline/rspec'
+
+RSpec.configure do |config|
+  # This disables ModelTimeline by default in tests for better performance
+  config.before(:suite) do
+    ModelTimeline.disable!
+  end
+
+  # Include the RSpec helpers and matchers
+  config.include ModelTimeline::RSpec
+end
+```
+
+#### Enabling Timeline in Tests
+
+ModelTimeline is disabled by default in tests for performance. Enable it selectively:
+
+```ruby
+# Enable timeline for a single test with metadata
+it 'tracks changes', :with_timeline do
+  # ModelTimeline is enabled here
+  user = create(:user)
+  expect(user.timeline_entries).to exist
+end
+
+# Enable timeline for a group of tests
+describe 'tracked actions', :with_timeline do
+  it 'tracks creation' do
+    post = create(:post)
+    expect(post.timeline_entries.count).to eq(1)
+  end
+
+  it 'tracks updates' do
+    post = create(:post)
+    post.update(title: 'New Title')
+    expect(post.timeline_entries.count).to eq(2)
+  end
+end
+
+# Tests without the metadata will have timeline disabled
+it 'does not track changes' do
+  user = create(:user)
+  expect(ModelTimeline::TimelineEntry.count).to eq(0)
+end
+```
+
+#### RSpec Matchers
+
+ModelTimeline provides several matchers for testing timeline entries:
+
+```ruby
+# Check for any timeline entries
+expect(user).to have_timeline_entries
+
+# Check for a specific number of entries
+expect(user).to have_timeline_entries(3)
+
+# Check for entries with a specific action
+expect(user).to have_timelined_action(:update)
+
+# Check if a specific attribute was changed
+expect(user).to have_timelined_change(:email)
+
+# Check if an attribute was changed to a specific value
+expect(user).to have_timelined_entry(:status, 'active')
+```
+
+These matchers make it easy to test that your application is correctly tracking model changes.
+
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/lib/model_timeline/configuration_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ModelTimeline
+  # Error raised when there's an issue with ModelTimeline configuration.
+  # This error is typically raised when attempting to define multiple timeline
+  # configurations for the same model and timeline entry class combination.
+  #
+  # @example Raising the error
+  #   raise ModelTimeline::ConfigurationError.new
+  #
+  # @example With custom message
+  #   raise ModelTimeline::ConfigurationError.new("Custom error message")
+  #
+  class ConfigurationError < StandardError
+    # Initialize a new ConfigurationError
+    #
+    # @param message [String] Custom error message
+    # @return [ModelTimeline::ConfigurationError] A new instance of ConfigurationError
+    def initialize(message = 'Multiple definitions of the same configuration found. ' \
+                             'Please ensure that each configuration is unique.')
+      super
+    end
+  end
+end

data/lib/model_timeline/controller_additions.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ModelTimeline
+  # Provides controller functionality for automatically tracking model timeline information.
+  # When included in a controller, this module will capture the current user and IP address
+  # for each request and make them available for timeline entries.
+  #
+  # @example Adding to a specific controller
+  #   class ApplicationController < ActionController::Base
+  #     include ModelTimeline::ControllerAdditions
+  #   end
+  #
+  # @example Using the class method
+  #   class ApplicationController < ActionController::Base
+  #     track_actions_with_model_timeline
+  #   end
+  #
+  module ControllerAdditions
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :set_model_timeline_info
+      after_action :clear_model_timeline_info
+    end
+
+    # Sets the current user and IP address in the request store.
+    # Called automatically as a before_action.
+    #
+    # @return [void]
+    def set_model_timeline_info
+      user = (send(ModelTimeline.current_user_method) if respond_to?(ModelTimeline.current_user_method, true))
+
+      ip = begin
+        if request.respond_to?(ModelTimeline.current_ip_method)
+          request.send(ModelTimeline.current_ip_method)
+        else
+          request.remote_ip
+        end
+      rescue StandardError
+        nil
+      end
+
+      ModelTimeline.store_user_and_ip(user, ip)
+    end
+
+    # Clears the request store after the request is complete.
+    # Called automatically as an after_action.
+    #
+    # @return [void]
+    def clear_model_timeline_info
+      ModelTimeline.clear_request_store
+    end
+
+    #   Class methods added to the including controller.
+    module ClassMethods
+      # Convenience method to include ModelTimeline::ControllerAdditions in a controller.
+      #
+      # @return [void]
+      def track_actions_with_model_timeline
+        include ModelTimeline::ControllerAdditions
+      end
+    end
+  end
+end

data/lib/model_timeline/generators/install_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module ModelTimeline
+  # Contains generators for setting up ModelTimeline in a Rails application.
+  # These generators help with creating necessary database tables and configurations.
+  module Generators
+    # Rails generator that creates the necessary migration file for ModelTimeline.
+    # his generator creates a migration to set up the timeline entries table.
+    #
+    # @example
+    #   $ rails generate model_timeline:install
+    #
+    # @example With custom table name
+    #   $ rails generate model_timeline:install --table_name=custom_timeline_entries
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      # @option options [String] :table_name ('model_timeline_timeline_entries')
+      #   The name to use for the timeline entries database table
+      class_option :table_name, type: :string, desc: 'Name for the timeline entries table'
+
+      #   Returns the next migration number to be used in the migration filename
+      #
+      # @param [String] dirname The directory where migrations are stored
+      # @return [String] The next migration number
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      # Creates the migration file for ModelTimeline tables
+      #
+      # @return [void]
+      def create_migration_file
+        @table_name = options[:table_name] || 'model_timeline_timeline_entries'
+        migration_template 'migration.rb.tt', 'db/migrate/create_model_timeline_tables.rb'
+      end
+    end
+  end
+end

data/lib/model_timeline/generators/templates/migration.rb.tt

@@ -0,0 +1,27 @@
+class CreateModelTimelineTables < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= @table_name %> do |t|
+      t.string :timelineable_type
+      t.bigint :timelineable_id
+      t.string :action, null: false
+
+      # Use PostgreSQL's JSONB type for better performance
+      t.jsonb :object_changes, default: {}, null: false
+
+      # Polymorphic user association
+      t.string :user_type
+      t.bigint :user_id
+      t.string :username
+
+      # IP address tracking
+      t.inet :ip_address
+
+      t.timestamps
+    end
+
+    add_index :<%= @table_name %>, [:timelineable_type, :timelineable_id], name: 'idx_timeline_on_timelineable'
+    add_index :<%= @table_name %>, [:user_type, :user_id], name: 'idx_timeline_on_user'
+    add_index :<%= @table_name %>, :object_changes, using: :gin, name: 'idx_timeline_on_changes'
+    add_index :<%= @table_name %>, :ip_address, name: 'idx_timeline_on_ip'
+  end
+end

data/lib/model_timeline/railtie.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ModelTimeline
+  # Rails integration for ModelTimeline.
+  # This Railtie automatically integrates ModelTimeline with Rails by:
+  #   - Including the Timelineable module in all ActiveRecord models
+  #   - Making controller helper methods available in all ActionControllers
+  #
+  # @example
+  #   # This class is automatically loaded by Rails, no manual inclusion required
+  #   # Rails.application.initialize!
+  #
+  class Railtie < Rails::Railtie
+    # @!method initializer(name, &block)
+    #   Initializes ModelTimeline by including necessary modules in Rails components.
+    #   Called automatically when Rails loads.
+    #
+    #   @param name [String] The name of the initializer
+    #   @param block [Proc] The initialization code to run
+    #   @return [void]
+    initializer 'model_timeline.initialize' do
+      ActiveSupport.on_load(:active_record) do
+        include Timelineable
+      end
+
+      ActiveSupport.on_load(:action_controller) do
+        include ControllerAdditions::ClassMethods
+      end
+    end
+  end
+end