trakable 0.2.0

data/lib/generators/trakable/templates/create_traks_migration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class CreateTraks < ActiveRecord::Migration[7.1]
+  def change
+    create_table :traks do |t|
+      t.string   :item_type,      null: false
+      t.bigint   :item_id,        null: false
+      t.string   :event,          null: false
+      t.text     :object
+      t.text     :changeset
+      t.string   :whodunnit_type
+      t.bigint   :whodunnit_id
+      t.text     :metadata
+      t.datetime :created_at, null: false
+    end
+
+    add_index :traks, %i[item_type item_id]
+    add_index :traks, :created_at
+    add_index :traks, %i[whodunnit_type whodunnit_id]
+    add_index :traks, :event
+    add_index :traks, %i[item_type created_at]
+  end
+end

data/lib/generators/trakable/templates/trakable_initializer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Trakable configuration
+# See https://github.com/hadrienblanc/trakable for more options
+
+Trakable.configure do |config|
+  # Enable/disable tracking globally
+  # config.enabled = true
+
+  # Attributes to ignore by default
+  # config.ignored_attrs = %w[created_at updated_at id]
+
+  # Controller method that returns the current user (default: :current_user)
+  # config.whodunnit_method = :current_user
+end

data/lib/trakable/cleanup.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Trakable
+  # Cleanup handles retention and max_traks pruning for Trak records.
+  #
+  # Intended to run from background jobs, not synchronously.
+  #
+  # Usage:
+  #   # Per-record cleanup
+  #   Trakable::Cleanup.run(record)
+  #
+  #   # Bulk retention cleanup (in a cron/background job)
+  #   Trakable::Cleanup.run_retention(Post)
+  #   Trakable::Cleanup.run_retention(Post, batch_size: 5_000)
+  #
+  class Cleanup
+    BATCH_SIZE = 1_000
+
+    attr_reader :record
+
+    def initialize(record)
+      @record = record
+    end
+
+    # Run cleanup for a single record.
+    #
+    # @param record [ActiveRecord::Base] The record with traks to clean up
+    #
+    def self.run(record)
+      new(record).run
+    end
+
+    def run # rubocop:disable Naming/PredicateMethod
+      enforce_max_traks
+      true
+    end
+
+    # Run retention cleanup for all records of a model class.
+    # Deletes in batches to avoid locking the table on large datasets.
+    #
+    # @param model_class [Class] The model class to clean up
+    # @param retention_period [Integer, nil] Override retention period in seconds
+    # @param batch_size [Integer] Number of rows to delete per batch (default: 1_000)
+    # @return [Integer, nil] Total number of deleted rows, or nil if no retention configured
+    #
+    def self.run_retention(model_class, retention_period: nil, batch_size: BATCH_SIZE)
+      retention = retention_period || model_class.trakable_options[:retention]
+      return nil unless retention
+
+      trak_class = resolve_trak_class
+      return 0 unless trak_class.respond_to?(:where)
+
+      cutoff = Time.now - retention
+      scope = trak_class.where(item_type: model_class.to_s)
+                        .where(trak_class.arel_table[:created_at].lt(cutoff))
+
+      delete_in_batches(scope, batch_size)
+    end
+
+    def self.resolve_trak_class
+      Trakable::Trak
+    end
+    private_class_method :resolve_trak_class
+
+    def self.delete_in_batches(scope, batch_size)
+      total = 0
+      loop do
+        deleted = scope.limit(batch_size).delete_all
+        total += deleted
+        break if deleted < batch_size
+      end
+      total
+    end
+    private_class_method :delete_in_batches
+
+    private
+
+    def enforce_max_traks
+      max = record.trakable_options[:max_traks]
+      return unless max
+      return unless record.respond_to?(:traks)
+
+      traks = record.traks
+      return unless traks.respond_to?(:where)
+
+      traks.order(created_at: :desc).offset(max).delete_all
+    end
+  end
+end

data/lib/trakable/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Trakable
+  # Stores global configuration for Trakable gem.
+  # Use Trakable.configure to set options.
+  class Configuration
+    attr_accessor :enabled, :whodunnit_method
+
+    def initialize
+      @enabled = true
+      @ignored_attrs = %w[created_at updated_at id]
+      @whodunnit_method = :current_user
+    end
+
+    # Ensure ignored_attrs are always stored as strings for performance
+    def ignored_attrs=(attrs)
+      @ignored_attrs = Array(attrs).map(&:to_s)
+    end
+
+    attr_reader :ignored_attrs
+  end
+end

data/lib/trakable/context.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Trakable
+  # Thread-safe context for storing whodunnit and tracking state
+  class Context
+    THREAD_KEY = :trakable_context
+
+    class << self
+      def whodunnit
+        context[:whodunnit]
+      end
+
+      def whodunnit=(value)
+        context[:whodunnit] = value
+      end
+
+      def metadata
+        context[:metadata]
+      end
+
+      def metadata=(value)
+        context[:metadata] = value
+      end
+
+      def tracking_enabled?
+        return Trakable.enabled? unless context.key?(:tracking_enabled)
+
+        context[:tracking_enabled]
+      end
+
+      def tracking_enabled=(value)
+        context[:tracking_enabled] = value
+      end
+
+      def with_user(user)
+        raise ArgumentError, 'with_user requires a block' unless block_given?
+
+        previous = whodunnit
+        self.whodunnit = user
+        yield
+      ensure
+        self.whodunnit = previous
+      end
+
+      def with_tracking
+        raise ArgumentError, 'with_tracking requires a block' unless block_given?
+
+        previous = context[:tracking_enabled]
+        self.tracking_enabled = true
+        yield
+      ensure
+        if previous.nil?
+          context.delete(:tracking_enabled)
+        else
+          self.tracking_enabled = previous
+        end
+      end
+
+      def without_tracking
+        raise ArgumentError, 'without_tracking requires a block' unless block_given?
+
+        previous = context[:tracking_enabled]
+        self.tracking_enabled = false
+        yield
+      ensure
+        if previous.nil?
+          context.delete(:tracking_enabled)
+        else
+          self.tracking_enabled = previous
+        end
+      end
+
+      def reset!
+        Thread.current.thread_variable_set(THREAD_KEY, nil)
+      end
+
+      private
+
+      def context
+        Thread.current.thread_variable_get(THREAD_KEY) ||
+          Thread.current.thread_variable_set(THREAD_KEY, {})
+      end
+    end
+  end
+end

data/lib/trakable/controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Trakable
+  # Controller concern for automatically setting whodunnit.
+  #
+  # Auto-included in ActionController::Base via Railtie.
+  # Uses Trakable.configuration.whodunnit_method (default: :current_user).
+  #
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      around_action :_set_trakable_whodunnit if respond_to?(:around_action)
+    end
+
+    private
+
+    def _set_trakable_whodunnit(&)
+      user = send(Trakable.configuration.whodunnit_method)
+      Trakable.with_user(user, &)
+    end
+  end
+end

data/lib/trakable/model.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+
+module Trakable
+  # Trakable Model Concern
+  #
+  # Include this in your ActiveRecord models to enable tracking:
+  #
+  #   class Post < ApplicationRecord
+  #     include Trakable::Model
+  #     trakable only: %i[title body], ignore: %i[views_count]
+  #   end
+  #
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      # Store trakable options at class level
+      class_attribute :trakable_options, instance_writer: false, default: {}
+
+      # has_many :traks association
+      has_many :traks, as: :item, class_name: 'Trakable::Trak', dependent: :nullify
+
+      # Include revertable methods
+      include ModelRevertable
+    end
+
+    class_methods do
+      # Configure tracking for this model
+      #
+      # Options:
+      #   only:          Array of attrs to track (default: all except ignored)
+      #   ignore:        Array of attrs to skip (default: global ignored_attrs)
+      #   if:            Proc/Method name - track only if true
+      #   unless:        Proc/Method name - skip tracking if true
+      #   on:            Array of events to track (default: %i[create update destroy])
+      #   callback_type: :after (default) or :after_commit
+      #
+      def trakable(options = {})
+        normalized = options.dup
+        callback_type = normalized.delete(:callback_type) || :after
+
+        # Pre-convert symbols to strings for performance
+        normalized[:only] = Array(normalized[:only]).map(&:to_s) if normalized[:only]
+        normalized[:ignore] = Array(normalized[:ignore]).map(&:to_s) if normalized[:ignore]
+
+        self.trakable_options = normalized
+
+        register_trakable_callbacks(normalized[:on], callback_type)
+      end
+
+      private
+
+      def register_trakable_callbacks(events, callback_type = :after)
+        events = Array(events).presence || %i[create update destroy]
+
+        if callback_type == :after_commit
+          register_after_commit_callbacks(events)
+        else
+          register_after_callbacks(events)
+        end
+      end
+
+      def register_after_callbacks(events)
+        events.each do |event|
+          case event.to_sym
+          when :create  then after_create :trak_create
+          when :update  then after_update :trak_update
+          when :destroy then after_destroy :trak_destroy
+          end
+        end
+      end
+
+      def register_after_commit_callbacks(events)
+        events.each do |event|
+          case event.to_sym
+          when :create  then after_commit(on: :create, &:trak_create)
+          when :update  then after_commit(on: :update, &:trak_update)
+          when :destroy then after_commit(on: :destroy, &:trak_destroy)
+          end
+        end
+      end
+    end
+
+    def trak_create
+      Trakable::Tracker.call(self, 'create')
+    end
+
+    def trak_update
+      Trakable::Tracker.call(self, 'update')
+    end
+
+    def trak_destroy
+      Trakable::Tracker.call(self, 'destroy')
+    end
+  end
+end

data/lib/trakable/railtie.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Trakable
+  class Railtie < ::Rails::Railtie
+    generators do
+      require 'generators/trakable/install_generator'
+    end
+
+    initializer 'trakable.configure' do |app|
+      if app.config.respond_to?(:trakable)
+        Trakable.configure do |config|
+          config.enabled = app.config.trakable.enabled if app.config.trakable.respond_to?(:enabled)
+          config.ignored_attrs = app.config.trakable.ignored_attrs if app.config.trakable.respond_to?(:ignored_attrs)
+          if app.config.trakable.respond_to?(:whodunnit_method)
+            config.whodunnit_method = app.config.trakable.whodunnit_method
+          end
+        end
+      end
+    end
+
+    # Auto-include Controller concern — no manual include needed
+    initializer 'trakable.controller' do
+      ActiveSupport.on_load(:action_controller_base) do
+        include Trakable::Controller
+      end
+    end
+  end
+end

data/lib/trakable/revertable.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Trakable
+  # Revertable provides methods for restoring previous states from Traks.
+  #
+  # Included in Trak to provide:
+  # - reify: Build a non-persisted record with state at this Trak
+  # - revert!: Restore the record to the state before this Trak
+  #
+  # Included in Model to provide:
+  # - trak_at: Get state at a specific timestamp
+  #
+  module Revertable
+    # Build a non-persisted record with the state stored in this Trak.
+    #
+    # For update/destroy traks, uses the object (state before change).
+    # For create traks, returns nil (no previous state exists).
+    #
+    # @return [ActiveRecord::Base, nil] Non-persisted record or nil for create events
+    #
+    # @example
+    #   trak = post.traks.last
+    #   previous_state = trak.reify
+    #   previous_state.title # => "Old Title"
+    #   previous_state.persisted? # => false
+    #
+    def reify
+      return nil if create?
+      return nil if object.nil? || object.empty?
+
+      current = item
+
+      # For update traks, delta storage requires the current record
+      # to reconstruct full previous state. Without it, return nil.
+      return nil if update? && current.nil?
+
+      model_class.new.tap do |record|
+        if current
+          current.attributes.except('id').each do |attr, val|
+            record.write_attribute(attr, val) if record.respond_to?(attr)
+          end
+        end
+        # Apply stored old values on top (delta or full snapshot)
+        object.each do |attr, value|
+          record.write_attribute(attr, value) if record.respond_to?(attr)
+        end
+      end
+    end
+
+    # Restore the record to the state before this Trak was created.
+    #
+    # For create traks: destroys the record
+    # For update traks: restores attributes before the change
+    # For destroy traks: re-creates the record with old attributes (new primary key)
+    #
+    # @param trak_revert [Boolean] Whether to create a new trak for this revert
+    # @return [ActiveRecord::Base, true, false] The restored record or true/false for success
+    #
+    # @example
+    #   post.traks.last.revert! # => restores previous state
+    #   post.traks.last.revert!(trak_revert: true) # => restores and creates a trak
+    #
+    def revert!(trak_revert: false)
+      case event
+      when 'create'
+        perform_revert_create(trak_revert: trak_revert)
+      when 'update'
+        perform_revert_update(trak_revert: trak_revert)
+      when 'destroy'
+        perform_revert_destroy(trak_revert: trak_revert)
+      end
+    end
+
+    private
+
+    def model_class
+      item_type.constantize
+    rescue NameError
+      raise "Cannot reify: model class #{item_type} not found"
+    end
+
+    def perform_revert_create(trak_revert:) # rubocop:disable Naming/PredicateMethod
+      target = item
+      return false unless target
+
+      Trakable.without_tracking { target.destroy }
+
+      build_revert_trak if trak_revert
+      true
+    end
+
+    def perform_revert_update(trak_revert:)
+      target = item
+      return false unless target
+
+      restored = reify
+      return false unless restored
+
+      Trakable.without_tracking do
+        object&.each do |attr, value|
+          target.write_attribute(attr, value) if target.respond_to?(attr)
+        end
+        target.save!(validate: false)
+      end
+
+      build_revert_trak if trak_revert
+      target
+    end
+
+    def perform_revert_destroy(trak_revert:)
+      restored = reify
+      return false unless restored
+
+      Trakable.without_tracking { restored.save!(validate: false) }
+
+      build_revert_trak(restored) if trak_revert
+      restored
+    end
+
+    def build_revert_trak(restored_item = nil)
+      Trakable::Tracker.call(restored_item || item, 'revert')
+    end
+  end
+
+  # Module for Model concern to add trak_at method
+  module ModelRevertable
+    # Get the state of this record at a specific point in time.
+    #
+    # @param timestamp [Time, DateTime] The point in time
+    # @return [ActiveRecord::Base, nil] Non-persisted record with state at that time, or nil
+    #
+    # @example
+    #   post.trak_at(1.day.ago) # => post state from 1 day ago
+    #   post.trak_at(Time.now + 1.hour) # => current state (future returns current)
+    #
+    def trak_at(timestamp)
+      timestamp = timestamp.to_time if timestamp.respond_to?(:to_time)
+
+      return nil if before_creation?(timestamp)
+
+      target_trak = find_trak_at(timestamp)
+
+      reify_or_dup(target_trak)
+    end
+
+    private
+
+    def before_creation?(timestamp)
+      respond_to?(:created_at) && created_at && timestamp < created_at
+    end
+
+    def find_trak_at(timestamp)
+      if traks.respond_to?(:where)
+        traks.where('created_at <= ?', timestamp).order(created_at: :desc).first
+      else
+        traks.select { |t| t.created_at <= timestamp }.max_by(&:created_at)
+      end
+    end
+
+    def reify_or_dup(target_trak)
+      return dup.tap { |r| r.id = nil } if target_trak.nil?
+
+      target_trak.reify || dup.tap { |r| r.id = nil }
+    end
+  end
+end

data/lib/trakable/tracker.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Trakable
+  # Tracker is responsible for building Trak records from ActiveRecord callbacks.
+  #
+  # Usage:
+  #   Trakable::Tracker.call(record, 'create')
+  #   Trakable::Tracker.call(record, 'update')
+  #   Trakable::Tracker.call(record, 'destroy')
+  #
+  class Tracker
+    attr_reader :record, :event
+
+    def initialize(record, event)
+      @record = record
+      @event = event.to_s
+    end
+
+    # Entry point: build a Trak for the given record/event
+    def self.call(record, event)
+      new(record, event).call
+    end
+
+    def call
+      return unless tracking_enabled?
+      return if skip?
+
+      build_trak
+    end
+
+    private
+
+    def tracking_enabled?
+      return false unless Trakable.enabled?
+
+      Context.tracking_enabled?
+    end
+
+    def skip?
+      return false unless trakable_record?
+
+      skip_if_condition? || skip_unless_condition?
+    end
+
+    def trakable_record?
+      return @trakable_record if defined?(@trakable_record)
+
+      @trakable_record = record.respond_to?(:trakable_options)
+    end
+
+    def skip_if_condition?
+      condition = record.trakable_options[:if]
+      condition && !record.instance_eval(&condition)
+    end
+
+    def skip_unless_condition?
+      condition = record.trakable_options[:unless]
+      condition && record.instance_eval(&condition)
+    end
+
+    def build_trak
+      trak = Trak.build(
+        item: record,
+        event: event,
+        changeset: changeset,
+        object: object_state,
+        whodunnit: whodunnit,
+        metadata: metadata
+      )
+      trak.save! if defined?(ActiveRecord::Base) && trak.is_a?(ActiveRecord::Base)
+      trak
+    end
+
+    def object_state
+      case event
+      when 'create'
+        nil
+      when 'update'
+        build_object_from_previous
+      else
+        record.attributes.except('id')
+      end
+    end
+
+    def changeset
+      return {} if event == 'destroy'
+
+      filter_changeset(record.previous_changes)
+    end
+
+    def filter_changeset(changes)
+      return {} if changes.empty?
+
+      result = apply_only_filter(changes)
+      apply_ignore_filter(result)
+    end
+
+    def apply_only_filter(changes)
+      return changes unless trakable_record?
+
+      only = record.trakable_options[:only]
+      return changes unless only
+
+      changes.slice(*only)
+    end
+
+    def apply_ignore_filter(changes)
+      ignore = []
+      if trakable_record?
+        record_ignore = record.trakable_options[:ignore]
+        ignore.concat(record_ignore) if record_ignore
+      end
+      global = Trakable.configuration.ignored_attrs
+      ignore.concat(global) if global&.any?
+      return changes unless ignore.any?
+
+      changes.except(*ignore)
+    end
+
+    def build_object_from_previous
+      delta = {}
+      record.previous_changes.each { |attr, (old, _)| delta[attr] = old }
+      delta
+    end
+
+    def whodunnit
+      Context.whodunnit
+    end
+
+    def metadata
+      Context.metadata
+    end
+  end
+end