tangledwires-audited 6.0.0

data/README.md

@@ -0,0 +1,447 @@
+TangledWires Audited
+[![Gem Version](https://img.shields.io/gem/v/tangledwires-audited.svg)](http://rubygems.org/gems/tangledwires-audited)
+![Build Status](https://github.com/TangledWiresOfficial/audited/actions/workflows/ci.yml/badge.svg)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+=======
+
+**Audited** (previously acts_as_audited) is an ORM extension that logs all changes to your models. Audited can also record who made those changes, save comments and associate models related to the changes.
+
+
+Audited currently (5.6) works with Rails 8.0, 7.2, 7.1, 7.0.
+
+## Supported Rubies
+
+Audited supports and is [tested against](https://github.com/TangledWiresOfficial/audited/actions/workflows/ci.yml) the following Ruby versions:
+
+* 2.3 (only tested on Sqlite due to testing issues with other DBs)
+* 2.4
+* 2.5
+* 2.6
+* 2.7
+* 3.0
+* 3.1
+* 3.2
+* 3.3
+
+Audited may work just fine with a Ruby version not listed above, but we can't guarantee that it will.
+
+## Supported ORMs
+
+Audited is currently ActiveRecord-only.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "tangledwires-audited"
+```
+
+And if you're using ```require: false``` you must add initializers like this:
+
+```ruby
+#./config/initializers/audited.rb
+require "audited"
+
+Audited::Railtie.initializers.each(&:run)
+```
+
+Then, from your Rails app directory, create the `audits` table:
+
+```bash
+$ rails generate audited:install
+$ rake db:migrate
+```
+
+By default, changes are stored in YAML format. If you're using PostgreSQL, then you can use `rails generate audited:install --audited-changes-column-type jsonb` (or `json` for MySQL 5.7+ and Rails 5+) to store audit changes natively with database JSON column types.
+
+If you're using something other than integer primary keys (e.g. UUID) for your User model, then you can use `rails generate audited:install --audited-user-id-column-type uuid` to customize the `audits` table `user_id` column type.
+
+#### Upgrading
+
+If you're already using Audited (or acts_as_audited), your `audits` table may require additional columns. After every upgrade, please run:
+
+```bash
+$ rails generate audited:upgrade
+$ rake db:migrate
+```
+
+Upgrading will only make changes if changes are needed.
+
+
+## Usage
+
+Simply call `audited` on your models:
+
+```ruby
+class User < ActiveRecord::Base
+  audited
+end
+```
+
+By default, whenever a user is created, updated or destroyed, a new audit is created.
+
+```ruby
+user = User.create!(name: "Steve")
+user.audits.count # => 1
+user.update!(name: "Ryan")
+user.audits.count # => 2
+user.destroy
+user.audits.count # => 3
+```
+
+Audits contain information regarding what action was taken on the model and what changes were made.
+
+```ruby
+user.update!(name: "Ryan")
+audit = user.audits.last
+audit.action # => "update"
+audit.audited_changes # => {"name"=>["Steve", "Ryan"]}
+```
+
+You can get previous versions of a record by index or date, or list all
+revisions.
+
+```ruby
+user.revisions
+user.revision(1)
+user.revision_at(Date.parse("2016-01-01"))
+```
+
+### Specifying columns
+
+By default, a new audit is created for any attribute changes. You can, however, limit the columns to be considered.
+
+```ruby
+class User < ActiveRecord::Base
+  # All fields
+  # audited
+
+  # Single field
+  # audited only: :name
+
+  # Multiple fields
+  # audited only: [:name, :address]
+
+  # All except certain fields
+  # audited except: :password
+end
+```
+
+### Specifying callbacks
+
+By default, a new audit is created for any Create, Update, Touch (Rails 6+) or Destroy action. You can, however, limit the actions audited.
+
+```ruby
+class User < ActiveRecord::Base
+  # All fields and actions
+  # audited
+
+  # Single field, only audit Update and Destroy (not Create or Touch)
+  # audited only: :name, on: [:update, :destroy]
+end
+```
+
+You can ignore the default callbacks globally unless the callback action is specified in your model using the `:on` option. To configure default callback exclusion, put the following in an initializer file (`config/initializers/audited.rb`):
+
+```ruby
+Audited.ignored_default_callbacks = [:create, :update] # ignore callbacks create and update
+```
+
+### Comments
+
+You can attach comments to each audit using an `audit_comment` attribute on your model.
+
+```ruby
+user.update!(name: "Ryan", audit_comment: "Changing name, just because")
+user.audits.last.comment # => "Changing name, just because"
+```
+
+You can optionally add the `:comment_required` option to your `audited` call to require comments for all audits.
+
+```ruby
+class User < ActiveRecord::Base
+  audited :comment_required => true
+end
+```
+
+You can update an audit only if audit_comment is present. You can optionally add the `:update_with_comment_only` option set to `false` to your `audited` call to turn this behavior off for all audits.
+
+```ruby
+class User < ActiveRecord::Base
+  audited :update_with_comment_only => false
+end
+```
+
+### Limiting stored audits
+
+You can limit the number of audits stored for your model. To configure limiting for all audited models, put the following in an initializer file (`config/initializers/audited.rb`):
+
+```ruby
+Audited.max_audits = 10 # keep only 10 latest audits
+```
+
+or customize per model:
+
+```ruby
+class User < ActiveRecord::Base
+  audited max_audits: 2
+end
+```
+
+Whenever an object is updated or destroyed, extra audits are combined with newer ones and the old ones are destroyed.
+
+```ruby
+user = User.create!(name: "Steve")
+user.audits.count # => 1
+user.update!(name: "Ryan")
+user.audits.count # => 2
+user.destroy
+user.audits.count # => 2
+```
+
+### Current User Tracking
+
+If you're using Audited in a Rails application, all audited changes made within a request will automatically be attributed to the current user. By default, Audited uses the `current_user` method in your controller.
+
+```ruby
+class PostsController < ApplicationController
+  def create
+    current_user # => #<User name: "Steve">
+    @post = Post.create(params[:post])
+    @post.audits.last.user # => #<User name: "Steve">
+  end
+end
+```
+
+To use a method other than `current_user`, put the following in an initializer file (`config/initializers/audited.rb`):
+
+```ruby
+Audited.current_user_method = :authenticated_user
+```
+
+Outside of a request, Audited can still record the user with the `as_user` method:
+
+```ruby
+Audited.audit_class.as_user(User.find(1)) do
+  post.update!(title: "Hello, world!")
+end
+post.audits.last.user # => #<User id: 1>
+```
+
+The standard Audited install assumes your User model has an integer primary key type. If this isn't true (e.g. you're using UUID primary keys), you'll need to create a migration to update the `audits` table `user_id` column type. (See Installation above for generator flags if you'd like to regenerate the install migration.)
+
+#### Custom Audit User
+
+You might need to use a custom auditor from time to time. This can be done by simply passing in a string:
+
+```ruby
+class ApplicationController < ActionController::Base
+  def authenticated_user
+    if current_user
+      current_user
+    else
+      'Alexander Fleming'
+    end
+  end
+end
+```
+
+`as_user` also accepts a string, which can be useful for auditing updates made in a CLI environment:
+
+```rb
+Audited.audit_class.as_user("console-user-#{ENV['SSH_USER']}") do
+  post.update_attributes!(title: "Hello, world!")
+end
+post.audits.last.user # => 'console-user-username'
+```
+
+If you want to set a specific user as the auditor of the commands in a CLI environment, whether that is a string or an ActiveRecord object, you can use the following command:
+
+```rb
+Audited.store[:audited_user] = "username"
+
+# or
+
+Audited.store[:audited_user] = User.find(1)
+```
+
+### Associated Audits
+
+Sometimes it's useful to associate an audit with a model other than the one being changed. For instance, given the following models:
+
+```ruby
+class User < ActiveRecord::Base
+  belongs_to :company
+  audited
+end
+
+class Company < ActiveRecord::Base
+  has_many :users
+end
+```
+
+Every change to a user is audited, but what if you want to grab all of the audits of users belonging to a particular company? You can add the `:associated_with` option to your `audited` call:
+
+```ruby
+class User < ActiveRecord::Base
+  belongs_to :company
+  audited associated_with: :company
+end
+
+class Company < ActiveRecord::Base
+  audited
+  has_many :users
+  has_associated_audits
+end
+```
+
+Now, when an audit is created for a user, that user's company is also saved alongside the audit. This makes it much easier (and faster) to access audits indirectly related to a company.
+
+```ruby
+company = Company.create!(name: "Collective Idea")
+user = company.users.create!(name: "Steve")
+user.update!(name: "Steve Richert")
+user.audits.last.associated # => #<Company name: "Collective Idea">
+company.associated_audits.last.auditable # => #<User name: "Steve Richert">
+```
+
+You can access records' own audits and associated audits in one go:
+```ruby
+company.own_and_associated_audits
+```
+
+### Conditional auditing
+
+If you want to audit only under specific conditions, you can provide conditional options (similar to ActiveModel callbacks) that will ensure your model is only audited for these conditions.
+
+```ruby
+class User < ActiveRecord::Base
+  audited if: :active?
+
+  def active?
+    last_login > 6.months.ago
+  end
+end
+```
+
+Just like in ActiveModel, you can use an inline Proc in your conditions:
+
+```ruby
+class User < ActiveRecord::Base
+  audited unless: Proc.new { |u| u.ninja? }
+end
+```
+
+In the above case, the user will only be audited when `User#ninja` is `false`.
+
+### Disabling auditing
+
+If you want to disable auditing temporarily doing certain tasks, there are a few
+methods available.
+
+To disable auditing on a save:
+
+```ruby
+@user.save_without_auditing
+```
+
+or:
+
+```ruby
+@user.without_auditing do
+  @user.save
+end
+```
+
+To disable auditing on a column:
+
+```ruby
+User.non_audited_columns = [:first_name, :last_name]
+```
+
+To disable auditing on an entire model:
+
+```ruby
+User.auditing_enabled = false
+```
+
+To disable auditing on all models:
+
+```ruby
+Audited.auditing_enabled = false
+```
+
+If you have auditing disabled by default on your model you can enable auditing
+temporarily.
+
+```ruby
+User.auditing_enabled = false
+@user.save_with_auditing
+```
+
+or:
+
+```ruby
+User.auditing_enabled = false
+@user.with_auditing do
+  @user.save
+end
+```
+
+### Encrypted attributes
+
+If you're using ActiveRecord's encryption (available from Rails 7) to encrypt some attributes, Audited will automatically filter values of these attributes. No additional configuration is required. Changes to encrypted attributes will be logged as `[FILTERED]`.
+
+```ruby
+class User < ActiveRecord::Base
+  audited
+  encrypts :password
+end
+```
+
+### Custom `Audit` model
+
+If you want to extend or modify the audit model, create a new class that
+inherits from `Audited::Audit`:
+```ruby
+class CustomAudit < Audited::Audit
+  def some_custom_behavior
+    "Hiya!"
+  end
+end
+```
+Then set it in an initializer:
+```ruby
+# config/initializers/audited.rb
+
+Audited.config do |config|
+  config.audit_class = "CustomAudit"
+end
+```
+
+### Enum Storage
+
+In 4.10, the default behavior for enums changed from storing the value synthesized by Rails to the value stored in the DB. You can restore the previous behavior by setting the store_synthesized_enums configuration value:
+
+```ruby
+# config/initializers/audited.rb
+
+Audited.store_synthesized_enums = true
+```
+
+## Support
+
+You can find documentation at: https://www.rubydoc.info/gems/audited
+
+Or join the [mailing list](http://groups.google.com/group/audited) to get help or offer suggestions.
+
+## Contributing
+
+In the spirit of [free software](http://www.fsf.org/licensing/essays/free-sw.html), **everyone** is encouraged to help improve this project. Here are a few ways _you_ can pitch in:
+
+* Use prerelease versions of Audited.
+* [Report bugs](https://github.com/TangledWiresOfficial/audited/issues).
+* Fix bugs and submit [pull requests](http://github.com/TangledWiresOfficial/audited/pulls).
+* Write, clarify or fix documentation.
+* Refactor code.

data/Rakefile

@@ -0,0 +1,16 @@
+#!/usr/bin/env rake
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rake/testtask"
+require "appraisal"
+
+RSpec::Core::RakeTask.new(:spec)
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+task default: [:spec, :test]

data/audited.gemspec

@@ -0,0 +1,38 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "audited/version"
+
+Gem::Specification.new do |gem|
+  gem.name = "tangledwires-audited"
+  gem.version = Audited::VERSION
+
+  gem.authors = ["TangledWires Ltd", "Brandon Keepers", "Kenneth Kalmer", "Daniel Morrison", "Brian Ryckbost", "Steve Richert", "Ryan Glover"]
+  gem.email = "support@tangledwires.co.uk"
+  gem.description = "Log all changes to your models"
+  gem.summary = gem.description
+  gem.homepage = "https://github.com/TangledWiresOfficial/audited"
+  gem.license = "MIT"
+
+  gem.files = `git ls-files`.split($\).reject { |f| f =~ /^(\.gemspec|\.git|\.standard|\.yard|gemfiles|test|spec)/ }
+
+  gem.required_ruby_version = ">= 2.3.0"
+
+  gem.add_dependency "activerecord", ">= 7.0", "< 8.2"
+  gem.add_dependency "activesupport", ">= 7.0", "< 8.2"
+
+  gem.add_development_dependency "appraisal"
+  gem.add_development_dependency "rails", ">= 7.0", "< 8.2"
+  gem.add_development_dependency "rspec-rails"
+  gem.add_development_dependency "standard"
+  gem.add_development_dependency "single_cov"
+
+  # JRuby support for the test ENV
+  if defined?(JRUBY_VERSION)
+    gem.add_development_dependency "activerecord-jdbcsqlite3-adapter", "~> 1.3"
+    gem.add_development_dependency "activerecord-jdbcpostgresql-adapter", "~> 1.3"
+    gem.add_development_dependency "activerecord-jdbcmysql-adapter", "~> 1.3"
+  else
+    gem.add_development_dependency "sqlite3", ">= 1.3.6"
+    gem.add_development_dependency "mysql2", ">= 0.3.20"
+    gem.add_development_dependency "pg", ">= 0.18", "< 2.0"
+  end
+end

data/lib/audited/audit.rb

@@ -0,0 +1,204 @@
+require "set"
+
+module Audited
+  # Audit saves the changes to ActiveRecord models.  It has the following attributes:
+  #
+  # * <tt>auditable</tt>: the ActiveRecord model that was changed
+  # * <tt>user</tt>: the user that performed the change; a string or an ActiveRecord model
+  # * <tt>action</tt>: one of create, update, or delete
+  # * <tt>audited_changes</tt>: a hash of all the changes
+  # * <tt>comment</tt>: a comment set with the audit
+  # * <tt>version</tt>: the version of the model
+  # * <tt>request_uuid</tt>: a uuid based that allows audits from the same controller request
+  # * <tt>created_at</tt>: Time that the change was performed
+  #
+
+  class YAMLIfTextColumnType
+    class << self
+      def load(obj)
+        if text_column?
+          ActiveRecord::Coders::YAMLColumn.new(Object).load(obj)
+        else
+          obj
+        end
+      end
+
+      def dump(obj)
+        if text_column?
+          ActiveRecord::Coders::YAMLColumn.new(Object).dump(obj)
+        else
+          obj
+        end
+      end
+
+      def text_column?
+        Audited.audit_class.columns_hash["audited_changes"].type.to_s == "text"
+      end
+    end
+  end
+
+  class Audit < ::ActiveRecord::Base
+    belongs_to :auditable,  polymorphic: true
+    belongs_to :user,       polymorphic: true
+    has_many :audit_associates
+
+    before_create :set_version_number, :set_audit_user, :set_request_uuid, :set_remote_address
+
+    cattr_accessor :audited_class_names
+    self.audited_class_names = Set.new
+
+    if ::ActiveRecord.version >= Gem::Version.new("7.1")
+      serialize :audited_changes, coder: YAMLIfTextColumnType
+    else
+      serialize :audited_changes, YAMLIfTextColumnType
+    end
+
+    scope :ascending, -> { reorder(version: :asc) }
+    scope :descending, -> { reorder(version: :desc) }
+    scope :creates, -> { where(action: "create") }
+    scope :updates, -> { where(action: "update") }
+    scope :destroys, -> { where(action: "destroy") }
+
+    scope :up_until, ->(date_or_time) { where("created_at <= ?", date_or_time) }
+    scope :from_version, ->(version) { where("version >= ?", version) }
+    scope :to_version, ->(version) { where("version <= ?", version) }
+    scope :auditable_finder, ->(auditable_id, auditable_type) { where(auditable_id: auditable_id, auditable_type: auditable_type) }
+    # Return all audits older than the current one.
+    def ancestors
+      self.class.ascending.auditable_finder(auditable_id, auditable_type).to_version(version)
+    end
+
+    def associates
+      audit_associates.map(&:associated)
+    end
+
+    # Return an instance of what the object looked like at this revision. If
+    # the object has been destroyed, this will be a new record.
+    def revision
+      clazz = auditable_type.constantize
+      (clazz.find_by_id(auditable_id) || clazz.new).tap do |m|
+        self.class.assign_revision_attributes(m, self.class.reconstruct_attributes(ancestors).merge(audit_version: version))
+      end
+    end
+
+    # Returns a hash of the changed attributes with the new values
+    def new_attributes
+      (audited_changes || {}).each_with_object({}.with_indifferent_access) do |(attr, values), attrs|
+        attrs[attr] = (action == "update") ? values.last : values
+      end
+    end
+
+    # Returns a hash of the changed attributes with the old values
+    def old_attributes
+      (audited_changes || {}).each_with_object({}.with_indifferent_access) do |(attr, values), attrs|
+        attrs[attr] = (action == "update") ? values.first : values
+      end
+    end
+
+    # Allows user to undo changes
+    def undo
+      case action
+      when "create"
+        # destroys a newly created record
+        auditable.destroy!
+      when "destroy"
+        # creates a new record with the destroyed record attributes
+        auditable_type.constantize.create!(audited_changes)
+      when "update"
+        # changes back attributes
+        auditable.update!(audited_changes.transform_values(&:first))
+      else
+        raise StandardError, "invalid action given #{action}"
+      end
+    end
+
+    # Allows user to be set to either a string or an ActiveRecord object
+    # @private
+    def user_as_string=(user)
+      # reset both either way
+      self.user_as_model = self.username = nil
+      user.is_a?(::ActiveRecord::Base) ?
+        self.user_as_model = user :
+        self.username = user
+    end
+    alias_method :user_as_model=, :user=
+    alias_method :user=, :user_as_string=
+
+    # @private
+    def user_as_string
+      user_as_model || username
+    end
+    alias_method :user_as_model, :user
+    alias_method :user, :user_as_string
+
+    # Returns the list of classes that are being audited
+    def self.audited_classes
+      audited_class_names.map(&:constantize)
+    end
+
+    # All audits made during the block called will be recorded as made
+    # by +user+. This method is hopefully threadsafe, making it ideal
+    # for background operations that require audit information.
+    def self.as_user(user)
+      last_audited_user = ::Audited.store[:audited_user]
+      ::Audited.store[:audited_user] = user
+      yield
+    ensure
+      ::Audited.store[:audited_user] = last_audited_user
+    end
+
+    # @private
+    def self.reconstruct_attributes(audits)
+      audits.each_with_object({}) do |audit, all|
+        all.merge!(audit.new_attributes)
+        all[:audit_version] = audit.version
+      end
+    end
+
+    # @private
+    def self.assign_revision_attributes(record, attributes)
+      attributes.each do |attr, val|
+        record = record.dup if record.frozen?
+
+        if record.respond_to?("#{attr}=")
+          record.attributes.key?(attr.to_s) ?
+            record[attr] = val :
+            record.send("#{attr}=", val)
+        end
+      end
+      record
+    end
+
+    # use created_at as timestamp cache key
+    def self.collection_cache_key(collection = all, *)
+      super(collection, :created_at)
+    end
+
+    private
+
+    def set_version_number
+      if action == "create"
+        self.version = 1
+      else
+        collection = (ActiveRecord::VERSION::MAJOR >= 6) ? self.class.unscoped : self.class
+        max = collection.auditable_finder(auditable_id, auditable_type).maximum(:version) || 0
+        self.version = max + 1
+      end
+    end
+
+    def set_audit_user
+      self.user ||= ::Audited.store[:audited_user] # from .as_user
+      self.user ||= ::Audited.store[:current_user].try!(:call) # from Sweeper
+      nil # prevent stopping callback chains
+    end
+
+    def set_request_uuid
+      self.request_uuid ||= ::Audited.store[:current_request_uuid]
+      self.request_uuid ||= SecureRandom.uuid
+    end
+
+    def set_remote_address
+      self.remote_address ||= ::Audited.store[:current_remote_address]
+    end
+  end
+end

data/lib/audited/audit_associate.rb

@@ -0,0 +1,8 @@
+module Audited
+  class AuditAssociate < ::ActiveRecord::Base
+    self.table_name_prefix = "audited_"
+
+    belongs_to :audit
+    belongs_to :associated, polymorphic: true
+  end
+end