active_snapshot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59dcd6fb412c1bb5f9fdc5bd9c447e4af9811837e0523da9cf7db4c12ce857fa
+  data.tar.gz: 31942b2cc72329c428f3a322d18d934b531bdd29b7e8a3dc956433dd0e822483
+SHA512:
+  metadata.gz: 367930717d8d578fe2ace8ddd3427a44f55fd52089e18862c7b0751dbc294ef6641c509d6b775fc3dc6e9f21e50ae9ef7b91e4b1c89a45b240da6b0343dbf7cf
+  data.tar.gz: ac0193a62d929e16ed19f8918b7fe1ad96b251819e98770add848d041ce7c4a7cad1771a158ca63130ed05e446ae53b2d0357cf4bb0a33a262c0e6de1543597e

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+CHANGELOG
+---------
+
+- **Unreleased**
+  * [View Diff](https://github.com/westonganger/active_snapshot/compare/v0.1.0...master)
+  * Nothing yet
+  
+- **v0.1.0** - Mar 5, 2021
+  * [View Diff](https://github.com/westonganger/active_snapshot/compare/edbbfd3...v0.1.0)
+  * Gem Initial Release

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Weston Ganger
+
+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,145 @@
+# ActiveSnapshot
+
+<a href="https://badge.fury.io/rb/active_snapshot" target="_blank"><img height="21" style='border:0px;height:21px;' border='0' src="https://badge.fury.io/rb/active_snapshot.svg" alt="Gem Version"></a>
+<a href='https://github.com/westonganger/active_snapshot/actions' target='_blank'><img src="https://github.com/westonganger/active_snapshot/workflows/Tests/badge.svg" style="max-width:100%;" height='21' style='border:0px;height:21px;' border='0' alt="CI Status"></a>
+<a href='https://rubygems.org/gems/active_snapshot' target='_blank'><img height='21' style='border:0px;height:21px;' src='https://ruby-gem-downloads-badge.herokuapp.com/active_snapshot?label=rubygems&type=total&total_label=downloads&color=brightgreen' border='0' alt='RubyGems Downloads' /></a>
+
+Simplified snapshots and restoration for ActiveRecord models and associations with a transparent white-box implementation.
+
+Key Features:
+
+- Create and Restore snapshots of a parent record and any specified child records
+- Predictible and explicit behaviour provides much needed clarity to your restore logic
+- Snapshots are created upon request only, we do not use any callbacks
+- Tiny method footprint so its easy to completely override the logic later
+
+Why This Library:
+
+Model Versioning and Restoration require concious thought, design, and understanding. You should understand your versioning and restoration process completely. This gem's small API and fully understandable design fully supports this.
+
+I do not recommend using paper_trail-association_tracking because it is mostly a blackbox solution which encourages you to set it up and then assume its Just Working<sup>TM</sup>. This makes for major data problems later. Dont fall into this trap. Instead read this gems brief source code completely before use OR copy the code straight into your codebase. Once you know it, then you are free.
+
+
+
+# Installation
+
+```ruby
+gem 'active_snapshot'
+```
+
+Then generate and run the necessary migrations to setup the `snapshots` and `snapshot_items` tables.
+
+```
+rails generate active_snapshot:install
+rake db:migrate
+```
+
+Then add `include ActiveSnapshot` to your ApplicationRecord or individual models.
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  include ActiveSortOrder
+end
+```
+
+This defines the following associations on your models:
+
+```ruby
+has_many :snapshots, as: :item, class_name: 'Snapshot'
+has_many :snapshot_items, as: :item, class_name: 'SnapshotItem'
+```
+
+It defines an optional extension to your model `has_snapshot_children`.
+
+It defines one instance method to your model: `create_snapshot!`
+
+# Basic Usage
+
+You now have access to the following methods:
+
+```ruby
+post = Post.first
+
+# Create snapshot grouped by identifier, only :identifier argument is required, all others are optional
+snapshot = post.create_snapshot!(
+  identifier: "snapshot_1", # Required
+  user: current_user,
+  metadata: {
+    foo: :bar
+  },
+)
+
+# Restore snapshot and all its child snapshots
+snapshot.restore!
+
+# Destroy snapshot and all its child snapshots
+# must be performed manually, snapshots and snapshot items are NEVER destroyed automatically
+snapshot.destroy!
+```
+
+# Restoring Associated / Child Records
+
+```ruby
+class Post < ActiveRecord::Base
+  include ActiveSnapshot
+  
+  has_snapshot_children do
+    ### Executed in the context of the instance / self
+
+    ### In this example, we choose to do a fresh load from the database of the record and all associated records from the database
+    instance = self.class.includes(:comments, :ip_address).find(id)
+    
+    ### Define the associated records that will be restored
+    {
+      comments: instance.comments,
+      tags: {
+        records: instance.tags
+      },
+      ip_address: {
+        record: instance.ip_address,
+        delete_method: ->(item){ item.release! }
+      }
+    }
+  end
+
+end
+```
+
+Now when you run `create_snapshot!` the associations will be tracked accordingly
+
+# Reifying Snapshot Items
+
+You can view all of the reified snapshot items by calling the following method. Its completely up to you on how to use this data. 
+
+```ruby
+reified_items = snapshot.fetch_reified_items
+```
+
+As a safety these records have the `@readonly = true` attribute set on them. If you want to perform any write actions on the returned instances you will have to set `@readonly = nil`.
+
+```ruby
+writable_reified_items = snapshot.fetch_reified_items.transform_values do |array| 
+  array.map{|x| x.instance_variable_set("@readonly", false); x}
+end
+```
+
+# Key Models Provided & Additional Customizations
+
+A key aspect of this library is its simplicity and small API. For major functionality customizations we encourage you to first delete this gem and then copy this gems code directly into your repository.
+
+I strongly encourage you to read the code for this library to understand how it works within your project so that you are capable of customizing the functionality later.
+
+- [SnapshotsConcern](./lib/active_snapshot/models/concerns/snapshots_concern.rb)
+  * Defines `snapshots` and `snapshot_items` has_many associations
+  * Defines `create_snapshot!` and `has_snapshot_children` methods
+- [Snapshot](./lib/active_snapshot/models/snapshot.rb)
+  * Contains a unique `identifier` column
+  * `has_many :item_snapshots`
+- [SnapshotItem](./lib/active_snapshot/models/snapshot_item.rb)
+  * Contains `object` column with yaml encoded model instance `attributes`
+  * `belongs_to :snapshot`
+
+
+# Credits
+
+Created & Maintained by [Weston Ganger](https://westonganger.com) - [@westonganger](https://github.com/westonganger)

data/Rakefile

@@ -0,0 +1,52 @@
+require File.expand_path(File.dirname(__FILE__) + '/lib/active_snapshot/version.rb')
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :db_prepare do
+  if ENV['CI'] != "true"
+    begin
+      require 'pg'
+
+      ### FOR LOCAL TESTING
+      `dropdb active_snapshot_test && createdb active_snapshot_test` rescue true
+    rescue LoadError
+      # Do nothing
+    end
+  end
+
+  Dir.chdir("test/dummy_app") do
+    ### Instantiates Rails
+    require File.expand_path("test/dummy_app/config/environment.rb", __dir__)
+
+    migration_path = "db/migrate"
+
+    ### Generate Migration
+    require "generators/active_snapshot/install/install_generator"
+
+    generator = ActiveSnapshot::InstallGenerator.new
+
+    Dir.glob(Rails.root.join(migration_path, "*#{generator.class::MIGRATION_NAME}.rb")).each do |f|
+      FileUtils.rm(f)
+    end
+
+    generator.create_migration_file
+  end ### END chdir
+end
+
+task default: [:db_prepare, :test]
+
+task :console do
+  require 'active_snapshot'
+
+  require_relative 'test/dummy_app/app/models/post'
+
+  require 'irb'
+  binding.irb
+end

data/lib/active_snapshot.rb

@@ -0,0 +1,17 @@
+require "active_record"
+require "activerecord-import"
+
+require "active_snapshot/version"
+
+require "active_snapshot/models/snapshot"
+require "active_snapshot/models/snapshot_item"
+
+require "active_snapshot/models/concerns/snapshots_concern"
+
+module ActiveSnapshot
+  extend ActiveSupport::Concern
+
+  included do
+    include ActiveSnapshot::SnapshotsConcern
+  end
+end

data/lib/active_snapshot/models/concerns/snapshots_concern.rb

@@ -0,0 +1,111 @@
+module ActiveSnapshot
+  module SnapshotsConcern
+    extend ActiveSupport::Concern
+
+    included do
+      ### We do NOT mark these as dependent: :destroy, the developer must manually destroy the snapshots or individual snapshot items
+      has_many :snapshots, as: :item, class_name: 'ActiveSnapshot::Snapshot'
+      has_many :snapshot_items, as: :item, class_name: 'ActiveSnapshot::SnapshotItem'
+    end
+
+    def create_snapshot!(identifier, user: nil, metadata: nil)
+      snapshot = snapshots.create!({
+        identifier: identifier,
+        user_id: (user.id if user),
+        user_type: (user.class.name if user),
+        metadata: (metadata || {}),
+      })
+
+      snapshot_items = []
+
+      snapshot_items << snapshot.build_snapshot_item(self)
+
+      snapshot_children = self.children_to_snapshot
+
+      if snapshot_children
+        snapshot_children.each do |child_group_name, h|
+          h[:records].each do |child_item|
+            snapshot_items << snapshot.build_snapshot_item(child_item, child_group_name: child_group_name)
+          end
+        end
+      end
+
+      SnapshotItem.import(snapshot_items, validate: true)
+
+      snapshot
+    end
+
+    class_methods do
+
+      def has_snapshot_children(&block)
+        if !block_given? && !defined?(@snapshot_children_proc)
+          raise ArgumentError.new("Invalid `has_snapshot_children` requires block to be defined")
+        elsif block_given?
+          @snapshot_children_proc = block
+        else
+          @snapshot_children_proc
+        end
+      end
+
+    end
+
+    def children_to_snapshot
+      snapshot_children_proc = self.class.has_snapshot_children
+
+      if !snapshot_children_proc
+        raise ArgumentError.new("`has_snapshot_children` must be defined on your class")
+      else
+        records = self.instance_exec(&snapshot_children_proc)
+
+        if records.is_a?(Hash)
+          records = records.with_indifferent_access
+        else
+          raise ArgumentError.new("Invalid `has_snapshot_children` definition. Must return a Hash")
+        end
+
+        snapshot_children = {}.with_indifferent_access
+
+        records.each do |assoc_name, opts|
+          snapshot_children[assoc_name] = {}
+
+          if opts.is_a?(ActiveRecord::Relation) || opts.is_a?(Array)
+            snapshot_children[assoc_name][:records] = opts
+
+          elsif opts.is_a?(Hash)
+            opts = opts.with_indifferent_access
+
+            records = opts[:records] || opts[:record]
+
+            if records
+              if records.respond_to?(:to_a)
+                records = records.to_a
+              else
+                records = [records]
+              end
+
+              snapshot_children[assoc_name][:records] = records
+            else
+              raise ArgumentError.new("Invalid `has_snapshot_children` definition. Must define a :records key for each child association.")
+            end
+
+            delete_method = opts[:delete_method]
+
+            if delete_method.present? && delete_method.to_s != "default"
+              if delete_method.respond_to?(:call)
+                snapshot_children[assoc_name][:delete_method] = delete_method
+              else
+                raise ArgumentError.new("Invalid `has_snapshot_children` definition. Invalid :delete_method argument. Must be a Lambda / Proc")
+              end
+            end
+
+          else
+            raise ArgumentError.new("Invalid `has_snapshot_children` definition. Invalid :records argument. Must be a Hash or Array")
+          end
+
+          return snapshot_children
+        end
+      end
+    end
+
+  end
+end

data/lib/active_snapshot/models/snapshot.rb

@@ -0,0 +1,104 @@
+module ActiveSnapshot
+  class Snapshot < ActiveRecord::Base
+    self.table_name = "snapshots"
+
+    if defined?(ProtectedAttributes)
+      attr_accessible :item_id, :item_type, :identifier, :user_id, :user_type
+    end
+
+    belongs_to :user, polymorphic: true
+    belongs_to :item, polymorphic: true
+    has_many :snapshot_items, class_name: 'ActiveSnapshot::SnapshotItem', dependent: :destroy
+
+    validates :item_id, presence: true
+    validates :item_type, presence: true
+    validates :identifier, presence: true, uniqueness: { scope: [:item_id, :item_type] }
+    validates :user_type, presence: true, if: :user_id
+
+    def metadata
+      @metadata ||= self[:metadata].with_indifferent_access
+    end
+
+    def metadata=(val)
+      @metadata = nil
+      self[:metadata] = val
+    end
+
+    def build_snapshot_item(instance, child_group_name: nil)
+      self.snapshot_items.new({
+        object: instance.attributes, 
+        item_id: instance.id,
+        item_type: instance.class.name,
+        child_group_name: child_group_name,
+      })
+    end
+
+    def restore!
+      ActiveRecord::Base.transaction do
+        ### Cache the child snapshots in a variable for re-use
+        cached_snapshot_items = snapshot_items.includes(:item)
+
+        existing_snapshot_children = item ? item.children_to_snapshot : []
+
+        if existing_snapshot_children.any?
+          children_to_keep = Set.new
+
+          cached_snapshot_items.each do |snapshot_item|
+            key = "#{snapshot_item.item_type} #{snapshot_item.item_id}"
+
+            children_to_keep << key
+          end
+
+          ### Destroy or Detach Items not included in this Snapshot's Items
+          ### We do this first in case you later decide to validate children in ItemSnapshot#restore_item! method
+          existing_snapshot_children.each do |child_group_name, h|
+            delete_method = h[:delete_method] || ->(child_record){ child_record.destroy! }
+
+            h[:records].each do |child_record|
+              child_record_id = child_record.send(child_record.class.send(:primary_key))
+
+              key = "#{child_record.class.name} #{child_record_id}"
+
+              if children_to_keep.exclude?(key)
+                delete_method.call(child_record)
+              end
+            end
+          end
+        end
+
+        ### Create or Update Items from Snapshot Items
+        cached_snapshot_items.each do |snapshot_item|
+          snapshot_item.restore_item!
+        end
+      end
+
+      return true
+    end
+
+    def fetch_reified_items
+      reified_children_hash = {}.with_indifferent_access
+
+      reified_parent = nil
+
+      snapshot_items.each do |si| 
+        reified_item = si.item_type.constantize.new(si.object)
+
+        reified_item.readonly!
+
+        key = si.child_group_name
+
+        if key
+          reified_children_hash[key] ||= []
+
+          reified_children_hash[key] << reified_item
+
+        elsif [self.item_id, self.item_type] == [si.item_id, si.item_type]
+          reified_parent = reified_item
+        end
+      end
+
+      return [reified_parent, reified_children_hash]
+    end
+
+  end
+end