simple_trail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db72b8ad5f7f566849b1f65a0ce90dbb9e69957614f794a6d263c8bba6fcbf39
+  data.tar.gz: 77ef1d353aa69bfd59f4b70c510b202d1c9212808a2d58db5e694ffcbb69407f
+SHA512:
+  metadata.gz: 73c11bee92e240153827cadff106c3b0b8afc7c5f83ed1ac98874c5ba1ed94d55633e8f7845b28521d6888427d4fa308b0c40fa731a6b2dea4adc021eef73ca2
+  data.tar.gz: 10a56e91186eb58487ab2a619dc0a6ec59e9406aa610fc8365acbaf34447dc324107aa2bf70a0d1f2229ec6ca3626dc62b9e401c3c9b217ae4cb6439b678bd3c

data/Rakefile

@@ -0,0 +1,28 @@
+#!/usr/bin/env rake
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+begin
+  require "bundler/setup"
+  require "yard"
+  YARD::Rake::YardocTask.new do |t|
+    t.files = ["lib/**/*.rb"]
+    t.files = ["app/models/simple_trail/*.rb"]
+  end
+rescue LoadError
+  puts "You must `bundle install` to run rake tasks"
+end
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+Bundler::GemHelper.install_tasks
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new(:rubocop)
+
+task default: %i[rubocop app:db:prepare spec]

data/app/models/simple_trail/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SimpleTrail
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/simple_trail/encrypted_history.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SimpleTrail
+  class EncryptedHistory < ::SimpleTrail::History
+    extend AttrEncrypted
+
+    attr_encrypted :note, key: NitroConfig.get_deferred!("encryption_key"),
+                          encode: true,
+                          insecure_mode: true,
+                          algorithm: "aes-256-cbc",
+                          mode: :single_iv_and_salt
+
+    before_save :clear_plain_note
+
+  private
+
+    def clear_plain_note
+      self[:note] = nil
+    end
+  end
+end

data/app/models/simple_trail/history.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SimpleTrail
+  class History < ::SimpleTrail::ApplicationRecord
+    serialize :source_changes, ::SimpleTrail::YAMLUnsafeCoder
+    serialize :backtrace, Array
+
+    default_scope { order("id DESC") }
+
+    scope :for_source, ->(source_object) do
+      where(source_id: source_object.id, source_type: source_object.class.to_s)
+    end
+
+    scope :in_natural_order, -> { reorder("id ASC") }
+
+    before_create :set_backtrace
+
+  private
+
+    def set_backtrace
+      self.backtrace = SimpleTrail::Config.backtrace_cleaner&.clean(caller) || caller
+    end
+  end
+end

data/config/database.yml

@@ -0,0 +1,7 @@
+development:
+  adapter:  sqlite3
+  database: db/simple_trail_development.sqlite
+
+test:
+  adapter:  sqlite3
+  database: db/simple_trail_test.sqlite

data/db/migrate/20200514201449_create_simple_trails.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/MethodLength
+class CreateSimpleTrails < ActiveRecord::Migration[6.0]
+  def change
+    create_table :"#{SimpleTrail.table_name_prefix}histories" do |t|
+      t.string :source_type
+      t.string :source_id
+      t.text :source_changes
+      t.integer :user_id
+      t.text :note
+      t.string :activity
+      t.text :encrypted_note
+      t.text :backtrace
+    end
+
+    add_index :"#{SimpleTrail.table_name_prefix}histories", %i[source_type source_id]
+  end
+end
+# rubocop:enable Metrics/MethodLength

data/docs/README.md

@@ -0,0 +1,74 @@
+## What is SimpleTrail
+
+SimpleTrail makes it easy to keep a history of attribute changes on a model
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'simple_trail'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install simple_trail
+
+
+# Configuration
+
+1. Add SimpleTrail config to your initializer file.
+2. You need to set `current_session_user_id` to include user info in `simple_trail_histories` table.
+3. You can optionally set `table_name_prefix` to customize default table name. Defaults to `simple_trail_histories`.
+4. SimpleTrail stores backtrace info in `simple_trail_histories`. It defaults to `Rails.backtrace_cleaner`. You can optionally set it to your customized backtrace cleaner.
+
+```ruby
+SimpleTrail.config do
+  table_name_prefix "myapp_"
+  current_session_user_id { MyApp.current_session_user_id }
+  backtrace_cleaner { YourCustom.backtrace_cleaner }
+end
+```
+
+## Usage
+
+```ruby
+class Project < ApplicationRecord
+  include ::SimpleTrail::Recordable
+end
+```
+
+Inlcude `simple_trail` in your lib files if you need to call it there:
+
+```ruby
+require "simple_trail"
+```
+
+
+Now you can access the object history through `SimpleTrail.for(object)` like:
+
+```ruby
+project = Project.create
+SimpleTrail.for(project).size
+# => 1
+```
+
+The user performing the action will be recorded from the Thread local `:user_id`.
+
+Then, require the engine in your `application.rb`
+
+```ruby
+require "simple_trail"
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/powerhome/power-tools.
+
+## License
+
+The package is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/simple_trail/config.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SimpleTrail
+  module Config
+  module_function
+
+    # SimpleTrail Stores backtrace info in `simple_trail_histories`
+    # It's config defaults to `Rails.backtrace_cleaner`
+    # You can optionally set it to your customized backtrace cleaner
+    # via `SimpleTrail.config.backtrace_cleaner = MyBacktraceCleaner`
+    mattr_accessor :backtrace_cleaner
+
+    # Allows to set configurion for SimpleTrail
+    def config(&block)
+      class_eval(&block)
+    end
+
+    # Optionally set `table_name_prefix` to customize default table name.
+    # Defaults to `simple_trail_histories`
+    def table_name_prefix(value)
+      SimpleTrail.table_name_prefix = value
+    end
+
+    # Sets `current_session_user_id` to include user info in `simple_trail_histories` table.
+    def current_session_user_id(&block)
+      @current_session_user_id = block if block
+      @current_session_user_id
+    end
+  end
+end

data/lib/simple_trail/engine.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SimpleTrail
+  class Engine < ::Rails::Engine
+    isolate_namespace SimpleTrail
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    config.generators do |g|
+      g.fixture_replacement :factory_bot, dir: "spec/factories"
+    end
+
+    initializer :append_migrations do |app|
+      unless app.root.to_s.match? root.to_s
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path
+        end
+      end
+    end
+
+    initializer "simple_trail.backtrace_cleaner" do
+      SimpleTrail::Config.backtrace_cleaner ||= Rails.backtrace_cleaner
+    end
+  end
+end

data/lib/simple_trail/entry_presenter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SimpleTrail
+  class EntryPresenter
+    delegate :backtrace,
+             :created_at,
+             :activity,
+             :source_type,
+             :source_id,
+             :source_changes,
+             :user_id,
+             :user,
+             :note,
+             :id,
+             to: :history, prefix: false
+    def initialize(history)
+      @history = history
+    end
+
+    # Details the changes made to the source object.
+    def describe_changes
+      @history.source_changes.map do |field, change|
+        describe_change(field, change)
+      end
+    end
+
+  private
+
+    attr_reader :history
+
+    def describe_change(field, change)
+      values = change.map { |value| format_value(field, value) }
+      return unless values.any?
+
+      from, to = *values
+      to = "nothing" if to.blank?
+      build_message(field, from, to)
+    rescue
+      "#{field}: #{from} - #{to}"
+    end
+
+    def format_value(field, val)
+      val = val.strftime("%m/%d/%Y") if val.respond_to?(:strftime)
+      val = val.map(&:humanize).join(", ") if val.is_a?(Array) && val.first.is_a?(String)
+      val = number_to_currency(val, precision: 2) if numeric?(field, val)
+      val
+    end
+
+    def build_message(field, from, to)
+      if to == true
+        "Selected #{field.to_s.titleize}"
+      elsif from == true
+        "Deselected #{field.to_s.titleize}"
+      elsif from.present?
+        "Changed #{field.to_s.titleize} from #{from} to #{to}"
+      else
+        "Changed #{field.to_s.titleize} to #{to}"
+      end
+    end
+
+    def numeric?(field, val)
+      field =~ /amount|price|cost|ceiling/i && val.respond_to?(:to_f) && val != ""
+    end
+  end
+end

data/lib/simple_trail/recordable.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SimpleTrail
+  module Recordable
+    extend ActiveSupport::Concern
+
+    included do
+      around_save :__record_changes
+    end
+
+    class_methods do
+      attr_reader :__simple_trail_source_changes
+
+      def history_options(source_changes: nil)
+        @__simple_trail_source_changes = source_changes
+      end
+    end
+
+  private
+
+    def __record_changes
+      activity = new_record? ? :created : :updated
+      yield
+      SimpleTrail.record!(self, activity, __simple_trail_source_changes,
+                          SimpleTrail::Config.current_session_user_id&.call)
+    end
+
+    def __simple_trail_source_changes
+      source_changes = self.class.__simple_trail_source_changes
+
+      case source_changes
+      when Proc then instance_exec(&source_changes)
+      when Symbol then send(source_changes)
+      else saved_changes
+      end
+    end
+  end
+end

data/lib/simple_trail/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SimpleTrail
+  # The current version of the gem.
+  VERSION = "0.1.0"
+end

data/lib/simple_trail/yaml_unsafe_coder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SimpleTrail
+  module YAMLUnsafeCoder
+  module_function
+
+    # Loads the object from YAML.
+    def load(payload)
+      return unless payload
+
+      if YAML.respond_to?(:unsafe_load)
+        YAML.unsafe_load(payload)
+      else
+        YAML.load(payload) # rubocop:disable Security/YAMLLoad
+      end
+    end
+
+    # Dumps the object to YAML.
+    def dump(obj)
+      YAML.dump obj
+    end
+  end
+end

data/lib/simple_trail.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "attr_encrypted"
+require "nitro_config"
+require "simple_trail/engine"
+require "simple_trail/entry_presenter"
+require "simple_trail/recordable"
+require "simple_trail/yaml_unsafe_coder"
+require "simple_trail/config"
+
+module SimpleTrail
+module_function
+
+  mattr_accessor(:table_name_prefix) { "simple_trail_" }
+
+  # Allows to set configurion for SimpleTrail
+  #
+  # SimpleTrail.config do
+  # configs to be set
+  # end
+  def config(...)
+    Config.config(...)
+  end
+
+  # Records a history activity for the given object
+  #
+  # @param object [#id] the object recording a history
+  # @param activity [Symbol] the activity that generated the history entry (i.e.: :created)
+  # @param changes [Hash] an ActiveRecord changes hash (i.e.: { 'name' => ['old', 'new'] })
+  # @param user_id [Integer] the id of the user triggered the history entry
+  # @param note [String] a note that can be attached to a history
+  # @param encrypted [Boolean] whether to encrypt or not the note
+  # @return [SimpleTrail::EntryPresenter]
+
+  # rubocop:disable Metrics/ParameterLists
+  def record!(object, activity, changes, user_id, note = nil, encrypted: false)
+    klass = encrypted ? SimpleTrail::EncryptedHistory : SimpleTrail::History
+
+    history = klass.for_source(object).create!(
+      source_changes: changes,
+      activity: activity,
+      user_id: user_id,
+      note: note
+    )
+    EntryPresenter.new(history)
+  end
+  # rubocop:enable Metrics/ParameterLists
+
+  # A collection of the history entries associated with the object
+  #
+  # @param object [#id] the object recording a history
+  # @return [Array<SimpleTrail::EntryPresenter>]
+  def for(object, encrypted: false, in_natural_order: false)
+    klass = encrypted ? SimpleTrail::EncryptedHistory : SimpleTrail::History
+
+    history_collection = in_natural_order ? klass.for_source(object).in_natural_order : klass.for_source(object)
+    history_collection.to_a.map do |history|
+      SimpleTrail::EntryPresenter.new(history)
+    end
+  end
+end

metadata

@@ -0,0 +1,219 @@
+--- !ruby/object:Gem::Specification
+name: simple_trail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gurban Haydarov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-03-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nitro_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: powerhome-attr_encrypted
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.6.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.6.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: license_finder
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.1.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.1.2
+- !ruby/object:Gem::Dependency
+  name: rubocop-powerhome
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.21
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.21
+description: SimpleTrail makes it easy to keep a history of attribute changes on a
+  model
+email:
+- gurban@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Rakefile
+- app/models/simple_trail/application_record.rb
+- app/models/simple_trail/encrypted_history.rb
+- app/models/simple_trail/history.rb
+- config/database.yml
+- db/migrate/20200514201449_create_simple_trails.rb
+- docs/README.md
+- lib/simple_trail.rb
+- lib/simple_trail/config.rb
+- lib/simple_trail/engine.rb
+- lib/simple_trail/entry_presenter.rb
+- lib/simple_trail/recordable.rb
+- lib/simple_trail/version.rb
+- lib/simple_trail/yaml_unsafe_coder.rb
+homepage: https://github.com/powerhome/power-tools
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key: 
+specification_version: 4
+summary: Simple way to track database changes
+test_files: []