draft_approve 0.1.0

data/lib/draft_approve/transaction.rb

@@ -0,0 +1,125 @@
+require 'draft_approve/errors'
+require 'draft_approve/models/draft_transaction'
+
+module DraftApprove
+
+  # Logic for handling ActiveRecord database transactions, and creating
+  # +DraftTransaction+ records.
+  #
+  # @api private
+  class Transaction
+
+    # Start a new database transaction, and create a new DraftTransaction to
+    # wrap the commands in the block.
+    #
+    # @param created_by [String] the user or process which created this
+    #   +DraftTransaction+ and the draft changes within it
+    # @param extra_data [Hash] any extra metadata to be stored with this
+    #   +DraftTransaction+
+    # @yield invokes the block, during which methods should be called to save
+    #   +Draft+ objects
+    #
+    # @return [DraftTransaction, nil] the resulting +DraftTransaction+, or +nil+
+    #   if no +Draft+ changes were saved within the given block
+    def self.in_new_draft_transaction(created_by: nil, extra_data: nil)
+      (draft_transaction, yield_return) = in_new_draft_transaction_helper(created_by: created_by, extra_data: extra_data) do
+        yield
+      end
+
+      # in_new_draft_transaction is used in Model.draft_transaction do ... blocks
+      # so we want to return the transaction itself to the caller
+      return draft_transaction
+    end
+
+    # Ensure the block is running in a database transaction and a
+    # +DraftTransaction+ - if there's not one already, create one.
+    #
+    # @param created_by [String] the user or process which created this
+    #   +DraftTransaction+ and the draft changes within it. Ignored if a
+    #   +DraftTransaction+ already exists within the scope of the current
+    #   thread / fiber.
+    # @param extra_data [Hash] any extra metadata to be stored with this
+    #   +DraftTransaction+. Ignored if a +DraftTransaction+ already exists
+    #   within the scope of the current thread / fiber.
+    # @yield invokes the block, during which methods should be called to save
+    #   +Draft+ objects
+    #
+    # @return [Object] the result of yielding to the given block
+    def self.ensure_in_draft_transaction(created_by: nil, extra_data: nil)
+      draft_transaction = current_draft_transaction
+
+      if draft_transaction
+        # There's an existing draft_transaction, just yield to the block
+        yield
+      else
+        # There's no transaction - start one and yield to the block inside the
+        # new transaction
+        (draft_transaction, yield_return) = in_new_draft_transaction_helper(created_by: created_by, extra_data: extra_data) do
+          yield
+        end
+
+        # ensure_in_draft_transaction is used in model.draft_save! method calls
+        # so we want to return the result of the yield (a draft object) to the caller
+        return yield_return
+      end
+    end
+
+    # Get the current +DraftTransaction+ for this thread / fiber, or raise an
+    # error if there is no current +DraftTransaction+
+    #
+    # @return [DraftTransaction]
+    def self.current_draft_transaction!
+      raise DraftApprove::Errors::NoDraftTransactionError unless current_draft_transaction.present?
+
+      current_draft_transaction
+    end
+
+    private
+
+    # Helper to create a new transaction and return both it and the result of
+    # yielding to the given block
+    def self.in_new_draft_transaction_helper(created_by: nil, extra_data: nil)
+      raise DraftApprove::Errors::NestedDraftTransactionError if current_draft_transaction.present?
+      draft_transaction, yield_return = nil
+
+      ActiveRecord::Base.transaction do
+        begin
+          draft_transaction = DraftTransaction.create!(
+            status: DraftTransaction::PENDING_APPROVAL,
+            created_by: created_by,
+            serialization: serialization_module,
+            extra_data: extra_data
+          )
+          self.current_draft_transaction = draft_transaction
+          yield_return = yield
+
+          # If no drafts exist at this point, this is a no-op Draft Transaction,
+          # so no point storing it - destroy it.
+          # NOTE: We don't rollback the transaction here, because non-draft
+          # changes may have occurred inside the yield block!
+          if draft_transaction.drafts.empty?
+            draft_transaction.destroy!
+            draft_transaction = nil
+          end
+        ensure
+          self.current_draft_transaction = nil
+        end
+      end
+
+      return draft_transaction, yield_return
+    end
+
+    def self.serialization_module
+      # TODO: Factor this out into a config setting or something...
+      DraftApprove::Serialization::Json
+    end
+
+    def self.current_draft_transaction
+      Thread.current[:draft_approve_transaction]
+    end
+
+    def self.current_draft_transaction=(draft_transaction)
+      Thread.current[:draft_approve_transaction] = draft_transaction
+    end
+  end
+end

data/lib/draft_approve/version.rb

@@ -0,0 +1,3 @@
+module DraftApprove
+  VERSION = "0.1.0"
+end

data/lib/generators/draft_approve/migration/migration_generator.rb

@@ -0,0 +1,41 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module DraftApprove
+  # @api private
+  module Generators
+    class MigrationGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path('../templates', __FILE__)
+
+      desc 'Generates the migrations for DraftApprove'
+
+      def create_migration_file
+        migration_template(
+          'create_draft_approve_tables.rb',
+          'db/migrate/create_draft_approve_tables.rb',
+          { migration_version: migration_version, json_type: json_type }
+        )
+      end
+
+      def self.next_migration_number(path)
+        next_migration_number = current_migration_number(path) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+
+      def json_type
+        if [:postgresql, :postgis].include? ActiveRecord::Base.connection.adapter_name.downcase.to_sym
+          'jsonb'
+        else
+          'json'
+        end
+      end
+    end
+  end
+end

data/lib/generators/draft_approve/migration/templates/create_draft_approve_tables.rb

@@ -0,0 +1,25 @@
+class CreateDraftApproveTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :draft_transactions, comment: 'Table linking multiple drafts to be applied in sequence, within a transaction' do |t|
+      t.string            :status,        null: false, index: true,  comment: 'The status of the drafts within this transaction (pending approval, approved, rejected, errored)'
+      t.string            :created_by,    null: true,  index: true,  comment: 'The user or process which created the drafts in this transaction'
+      t.string            :reviewed_by,   null: true,  index: true,  comment: 'The user who approved or rejected the drafts in this transaction'
+      t.string            :review_reason, null: true,  index: false, comment: 'The reason given by the user for approving or rejecting the drafts in this transaction'
+      t.string            :error,         null: true,  index: false, comment: 'If there was an error while approving this transaction, more information on the error that occurred'
+      t.string            :serialization, null: false, index: false, comment: 'The serialization module used for all drafts within this transaction'
+      t.<%= json_type %>  :extra_data,    null: true,  index: false, comment: 'Any extra data associated with this draft transaction, eg. users / roles who are authorised to approve the changes'
+
+      t.timestamps
+    end
+
+    create_table :drafts, comment: 'Drafts of changes to be approved' do |t|
+      t.references        :draft_transaction,   null: false, index: true, foreign_key: true
+      t.references        :draftable,           null: true,  index: true, polymorphic: true
+      t.string            :draft_action_type,   null: false
+      t.<%= json_type %>  :draft_changes,       null: false
+      t.<%= json_type %>  :draft_options,       null: true
+
+      t.timestamps
+    end
+  end
+end

metadata

@@ -0,0 +1,253 @@
+--- !ruby/object:Gem::Specification
+name: draft_approve
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrew Sibley
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2019-02-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !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: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.18'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.18'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.11'
+- !ruby/object:Gem::Dependency
+  name: codecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.18
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.18
+description: "\n    All draft data is saved in a separate table, so no need to worry
+  about\n    existing code / SQL accidentally finding non-approved data. Supports
+  draft\n    changes to existing objects, and creating new objects as drafts. Supports\n
+  \   'draft transactions' which may update / create many objects, and must be\n    approved
+  / rejected in their entirety.\n  "
+email:
+- andrew.s@38degrees.org.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- ".yardopts"
+- Appraisals
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.md
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- draft_approve.gemspec
+- lib/draft_approve.rb
+- lib/draft_approve/draft_changes_proxy.rb
+- lib/draft_approve/draftable/base_class_methods.rb
+- lib/draft_approve/draftable/class_methods.rb
+- lib/draft_approve/draftable/instance_methods.rb
+- lib/draft_approve/errors.rb
+- lib/draft_approve/models/draft.rb
+- lib/draft_approve/models/draft_transaction.rb
+- lib/draft_approve/persistor.rb
+- lib/draft_approve/serialization/json.rb
+- lib/draft_approve/serialization/json/constants.rb
+- lib/draft_approve/serialization/json/draft_changes_proxy.rb
+- lib/draft_approve/serialization/json/serializer.rb
+- lib/draft_approve/transaction.rb
+- lib/draft_approve/version.rb
+- lib/generators/draft_approve/migration/migration_generator.rb
+- lib/generators/draft_approve/migration/templates/create_draft_approve_tables.rb
+homepage: https://github.com/38dgs/draft_approve
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.8
+signing_key: 
+specification_version: 4
+summary: Save drafts of ActiveRecord models & approve them to apply the changes.
+test_files: []