petra_core 0.0.1

data/lib/petra/components/transaction.rb

@@ -0,0 +1,405 @@
+# frozen_string_literal: true
+
+require 'petra/components/entry_set'
+require 'petra/components/section'
+require 'petra/components/proxy_cache'
+require 'continuation'
+
+module Petra
+  module Components
+    class Transaction
+      include ActiveSupport::Callbacks
+
+      attr_reader :identifier
+      attr_reader :persisted
+      attr_reader :committed
+      attr_reader :reset
+      attr_reader :retry_in_progress
+
+      alias persisted? persisted
+      alias committed? committed
+      alias reset? reset
+      alias retry_in_progress? retry_in_progress
+
+      delegate :log_attribute_change,
+               :log_object_persistence,
+               :log_attribute_read,
+               :log_object_initialization,
+               :log_object_destruction, to: :current_section
+
+      def initialize(identifier:)
+        @identifier        = identifier
+        @persisted         = false
+        @committed         = false
+        @reset             = false
+        @retry_in_progress = false
+      end
+
+      def after_initialize
+        # Initialize the current section
+        current_section
+      end
+
+      #----------------------------------------------------------------
+      #                          Callbacks
+      #----------------------------------------------------------------
+
+      define_callbacks :commit, :rollback, :reset
+      define_callbacks :persist
+
+      #----------------------------------------------------------------
+      #                          Log Entries
+      #----------------------------------------------------------------
+
+      #
+      # Returns the latest value which was set for a certain object attribute.
+      # This means that all previous sections' write sets are inspected from new to old.
+      #
+      # @see Petra::Components::Section#value_for for more information
+      #
+      def attribute_value(proxy, attribute:)
+        sections.reverse.find { |s| s.value_for?(proxy, attribute: attribute) }.value_for(proxy, attribute: attribute)
+      end
+
+      #
+      # Checks whether the given attribute has been changed during the transaction.
+      # It basically searches for a matching write set entry in all previous (and current) sections.
+      # If such an entry exists AND there hasn't been an attribute change veto which is newer than it,
+      # the attribute counts as "changed within the transaction".
+      #
+      # @return [Boolean] +true+ if there there was a valid attribute change
+      #
+      def attribute_value?(proxy, attribute:)
+        sections.reverse.any? { |s| s.value_for?(proxy, attribute: attribute) } &&
+          !attribute_change_veto?(proxy, attribute: attribute)
+      end
+
+      #
+      # @return [Boolean] +true+ if the given attribute was read in one of the previous (or the current) sections
+      #
+      def read_attribute_value?(proxy, attribute:)
+        sections.reverse.any? { |s| s.read_value_for?(proxy, attribute: attribute) }
+      end
+
+      #
+      # @return [Object] the last read value for the given attribute
+      #
+      def read_attribute_value(proxy, attribute:)
+        sections
+          .reverse.find { |s| s.read_value_for?(proxy, attribute: attribute) }
+          .read_value_for(proxy, attribute: attribute)
+      end
+
+      alias attribute_changed? attribute_value?
+      alias attribute_read? read_attribute_value?
+
+      #
+      # @return [Petra::Components::EntrySet] the combined log entries of all sections from old to new
+      #
+      # TODO: Cache entries from already persisted sections.
+      #
+      def log_entries
+        sections.each_with_object(EntrySet.new) { |s, es| es.concat(s.log_entries) }
+      end
+
+      #
+      # @param [Petra::Proxies::ObjectProxy] proxy
+      #
+      # @param [String, Symbol] attribute
+      #
+      # @param [Object] external_value
+      #   The current external value. It is needed as read integrity overrides
+      #   only stay active as long as the external value stays the same.
+      #
+      # @return [Boolean] +true+ if ReadIntegrityErrors should still be suppressed for
+      #   the given attribute. This is the case if a ReadIntegrityOverride log entry is still
+      #   active
+      #
+      def read_integrity_override?(proxy, attribute:, external_value:)
+        # Step 1: Search for the latest read integrity override entry we have for the given attribute
+        attribute_entries = log_entries.for_attribute_key(proxy.__attribute_key(attribute))
+        rio_entry         = attribute_entries.of_kind(:read_integrity_override).latest
+
+        # If there was no override in the past sections, there can't be an active one
+        return false unless rio_entry
+
+        # Step 2: Find the read log entry we previously created for this attribute.
+        #   There has to be one as otherwise no read integrity error could have happened.
+        read_entry = attribute_entries.of_kind(:attribute_read).latest
+
+        # Step 3: Test if the read entry is newer than the RIO entry.
+        #   If that's the case, the user most likely decided that the new external
+        #   value should be displayed inside the transaction.
+        #   As we could have only landed here if the external value changed again,
+        #   we probably have to re-raise an exception about that.
+        return false if read_entry > rio_entry
+
+        # Step 4: We found ourselves a RIO entry that has not yet been invalidated
+        #   by another attribute read, good.
+        #   Now we have to check whether the current external value is still
+        #   the same as at the time we generated the RIO entry.
+        #   If that's the case, we still have an active read integrity override.
+        rio_entry.external_value == external_value
+      end
+
+      #
+      # @param [Petra::Proxies::ObjectProxy] proxy
+      #
+      # @param [String, Symbol] attribute
+      #
+      # @return [Boolean] +true+ if there is an active AttributeChangeVeto
+      #   for the given attribute, meaning that all attribute changes
+      #   should be discarded.
+      #
+      # TODO: Combine with #read_integrity_override, because DRY
+      #
+      def attribute_change_veto?(proxy, attribute:)
+        # Step 1: Search for the latest attribute change veto entry we have for the given attribute
+        attribute_entries = log_entries.for_attribute_key(proxy.__attribute_key(attribute))
+        acv_entry         = attribute_entries.of_kind(:attribute_change_veto).latest
+
+        # If there hasn't been an attribute change veto in the past, there can't be an active one
+        return false unless acv_entry
+
+        # Step 2: Find the latest attribute change entry we have for the given attribute
+        change_entry = attribute_entries.of_kind(:attribute_change).latest
+
+        # Step 3: Check if the change entry is newer than the ACV entry
+        #   If so, the ACV entry is no longer valid
+        change_entry < acv_entry
+      end
+
+      #----------------------------------------------------------------
+      #                        Attribute Helpers
+      #----------------------------------------------------------------
+
+      #
+      # Checks whether the given attribute has been changed since we last read it.
+      # Raises an exception if the attribute was changed externally
+      #
+      # We cannot check here whether the attribute had several different values before
+      # going back to the original one, so we only compare the current and the last read value.
+      #
+      # @param [Boolean] force
+      #   If set to +true+, the check is performed even if it was disabled in the
+      #   base configuration.
+      #
+      # @raise [Petra::ReadIntegrityError] Raised if an attribute that we previously read,
+      #   but NOT changed was changed externally
+      #
+      # @raise [Petra::ReadWriteIntegrityError] Raised if an attribute that we previously read AND
+      #   changed was changed externally
+      #
+      def verify_attribute_integrity!(proxy, attribute:, force: false)
+        # If we didn't read the attribute before, we can't search for changes
+        return unless attribute_read?(proxy, attribute: attribute)
+
+        # Don't perform the check if the force flag is not set and
+        # petra is configured to not fail on read integrity errors at all.
+        return if !force && !Petra.configuration.instant_read_integrity_fail
+
+        # New objects won't be changed externally...
+        return if proxy.__new?
+
+        external_value  = proxy.unproxied.send(attribute)
+        last_read_value = read_attribute_value(proxy, attribute: attribute)
+
+        # If nothing changed, we're done
+        return if external_value == last_read_value
+
+        # The user has previously chosen to ignore the external changes to this attribute (using ignore!).
+        # Therefore, we do not have to raise another exception
+        # OR
+        # We only read this attribute before.
+        # If the user (/developer) previously placed a read integrity override
+        # for the current external value, we don't have to re-raise an exception about the change
+        return if read_integrity_override?(proxy, attribute: attribute, external_value: external_value)
+
+        if attribute_changed?(proxy, attribute: attribute)
+          # We read AND changed this attribute before
+
+          # If there is already an active attribute change veto (meaning that we didn't change
+          # the attribute again after the last one), we don't have to raise another exception about it.
+          # TODO: This should have already been filtered out by #attribute_changed?
+          # return if attribute_change_veto?(proxy, attribute: attribute)
+
+          callcc do |continuation|
+            exception = Petra::WriteClashError.new(attribute:      attribute,
+                                                   object:         proxy,
+                                                   our_value:      attribute_value(proxy, attribute: attribute),
+                                                   external_value: external_value,
+                                                   continuation:   continuation)
+
+            fail exception, "The attribute `#{attribute}` has been changed externally and in the transaction."
+          end
+        else
+          callcc do |continuation|
+            exception = Petra::ReadIntegrityError.new(attribute:       attribute,
+                                                      object:          proxy,
+                                                      last_read_value: last_read_value,
+                                                      external_value:  external_value,
+                                                      continuation:    continuation)
+            fail exception, "The attribute `#{attribute}` has been changed externally."
+          end
+        end
+      end
+
+      #----------------------------------------------------------------
+      #                         Object Helpers
+      #----------------------------------------------------------------
+
+      def objects
+        @objects ||= ProxyCache.new(self)
+      end
+
+      #----------------------------------------------------------------
+      #                           Sections
+      #----------------------------------------------------------------
+
+      def current_section
+        @current_section ||= Petra::Components::Section.new(self).tap do |s|
+          sections << s
+        end
+      end
+
+      def sections
+        # TODO: Acquire the transaction lock once here, otherwise, every section will do it.
+        @sections ||= begin
+          persistence_adapter.with_transaction_lock(self) do
+            persistence_adapter.savepoints(self).map do |savepoint|
+              Petra::Components::Section.new(self, savepoint: savepoint)
+            end.sort_by(&:savepoint_version)
+          end
+        end
+      end
+
+      #----------------------------------------------------------------
+      #                        Transaction Handling
+      #----------------------------------------------------------------
+
+      #
+      # Tries to commit the current transaction
+      #
+      def commit!
+        run_callbacks :commit do
+          # Step 1: Lock this transaction so no other thread may alter it any more
+          persistence_adapter.with_transaction_lock(identifier) do
+            # Step 2: Try to get the locks for all objects which took part in this transaction
+            #   Acquire the locks on a sorted collection to avoid Deadlocks with other transactions
+            # We do not have to lock objects which were created within the transaction
+            #   as the cannot be altered outside of it and the transaction itself is locked.
+            with_locked_objects(objects.fateful.sort.reject(&:__new?), suspend: false) do
+              # Step 3: Now that we got locks on all objects used during this transaction,
+              #   we can check whether all read attributes still have the same value.
+              #   If that's not the case, we may not proceed.
+              objects.verify_read_attributes!(force: true)
+
+              # Step 4: Now that we know that all read values are still valid,
+              #   we may actually apply all the changes we previously logged.
+              sections.each(&:apply_log_entries!)
+
+              @committed = true
+              Petra.logger.info "Committed transaction #{@identifier}", :blue, :underline
+
+              # Step 5: Wow, me made it this far!
+              #   Now it's time to clean up and remove the data we previously persisted for this
+              #   transaction before releasing the lock on all of the objects and the transaction itself.
+              # TODO: See if this causes problems with other threads working on this transactions. Probably keep
+              #   the entries around and just mark the transaction as committed?
+              #   Idea: keep it and add a last log entry like `transaction_commit` and persist it.
+              persistence_adapter.reset_transaction(self)
+            end
+          end
+        rescue Petra::ReadIntegrityError # One (or more) of the attributes from our read set changed externally
+          raise
+        rescue Petra::LockError # One (or more) of the objects could not be locked.
+          #   The object locks are freed by itself, but we have to notify
+          #   the outer application about this commit error
+          raise
+        end
+      end
+
+      #
+      # Make sure that overrides (ReadIntegrityOverride / AttributeChangeVeto) are persisted
+      # before retrying a section. If we don't persist those, the same error will simply happen again
+      # in the next iteration.
+      #
+      def prepare_for_retry!
+        @retry_in_progress = true
+        current_section.prepare_for_retry!
+        persistence_adapter.persist!
+        @retry_in_progress = false
+      end
+
+      #
+      # Performs a rollback on this transaction, meaning that it will be set
+      # to the state of the latest savepoint.
+      # The current section will be reset, but keep the same savepoint name.
+      #
+      def rollback!
+        run_callbacks :rollback do
+          current_section.reset! unless current_section.persisted?
+          Petra.logger.debug "Rolled back section #{current_section.savepoint}", :yellow
+        end
+      end
+
+      #
+      # Persists the current transaction section using the configured persistence adapter
+      #
+      def persist!
+        run_callbacks :persist do
+          current_section.enqueue_for_persisting!
+          persistence_adapter.persist!
+          Petra.logger.debug "Persisted transaction #{@identifier}", :green
+          @persisted = true
+        end
+      end
+
+      #
+      # Completely dismisses the current transaction and removes it from the persistence storage
+      #
+      def reset!
+        run_callbacks :reset do
+          persistence_adapter.reset_transaction(self)
+          @sections = []
+          Petra.logger.warn "Reset transaction #{@identifier}", :red
+        end
+      end
+
+      private
+
+      #
+      # Tries to acquire locks on all of the given proxies and executes
+      # the given block afterwards.
+      #
+      # Please note that the objects may still be altered outside of transactions.
+      #
+      # This ensures that all object locks are released if an exception occurs
+      #
+      # @param [Array<Petra::Proxies::ObjectProxy>] proxies
+      #
+      # @raise [Petra::LockError] If +suspend+ is set to +false+, a LockError is raised
+      #   if one of the object locks could not be acquired
+      #
+      # TODO: Many objects, many SystemStackErrors?
+      #
+      def with_locked_objects(proxies, suspend: true, &block)
+        if proxies.empty?
+          yield
+        else
+          persistence_adapter.with_object_lock(proxies.first, suspend: suspend) do
+            with_locked_objects(proxies[1..-1], suspend: suspend, &block)
+          end
+        end
+      end
+
+      #
+      # @return [Petra::PersistenceAdapters::Adapter] the current persistence adapter
+      #
+      def persistence_adapter
+        Petra.transaction_manager.persistence_adapter
+      end
+
+    end
+  end
+end

data/lib/petra/components/transaction_manager.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require 'petra/components/transaction'
+
+module Petra
+  module Components
+    #
+    # A transaction manager handles the transactions in a single petra section,
+    # when speaking in terms of Rails, a new transaction manager is built every request.
+    #
+    # Each TransactionManager has a stack of transactions which are currently active and
+    # is currently stored within the current thread space. Once all active transactions
+    # are either persisted or otherwise finished, it is removed again to (more or less)
+    # ensure thread safety.
+    #
+    class TransactionManager
+
+      #
+      # Performs the given block on the current instance of TransactionManager.
+      # For nested transactions, the outer transaction manager is re-used,
+      # for outer transactions, a new manager is created.
+      #
+      # Once all running transactions either failed or were committed/persisted,
+      # the transaction manager instance is removed from the thread local space again.
+      #
+      # @todo: See if that is still a good practise when it comes to
+      #        offering further actions through exception callbacks
+      #
+      def self.within_instance(&block)
+        instance = Thread.current[:__petra_transaction_manager] ||= TransactionManager.new
+        begin
+          instance.instance_eval(&block)
+        ensure
+          Thread.current[:__petra_transaction_manager] = nil if instance&.transaction_count&.zero?
+        end
+      end
+
+      #
+      # @return [Petra::Components::TransactionManager, NilClass] the currently active TransactionManager
+      #   if there is at least one running transaction.
+      #
+      def self.instance
+        Thread.current[:__petra_transaction_manager] || fail(Petra::PetraError, 'There are no running transactions')
+      end
+
+      #
+      # @return [Boolean] +true+ if at least one transaction is currently running.
+      #
+      # Please note that a transaction is only considered running if the process is currently
+      # in its execution block, even if it has uncommitted changes.
+      #
+      def self.instance?
+        !!Thread.current[:__petra_transaction_manager]
+      end
+
+      def initialize
+        @stack = []
+      end
+
+      #
+      # Resets the currently innermost transaction.
+      # This means that everything this transaction has done so far will be
+      # discarded and the identifier freed again.
+      # TODO: Nested transactions again, what would happen?
+      #
+      def reset_transaction
+        @stack.last.reset!
+        fail Petra::AbortTransaction
+      end
+
+      #
+      # Performs a rollback on the currently innermost transaction.
+      # This means that everything up until the transaction's latest
+      # savepoint will be discarded.
+      # TODO: Can we jump to a custom savepoint? What would happen if we were using the outer transaction's data?
+      #
+      def rollback_transaction
+        @stack.last.rollback!
+        fail Petra::AbortTransaction
+      end
+
+      #
+      # Commits the currently innermost transaction
+      #
+      def commit_transaction
+        @stack.last.commit!
+        fail Petra::AbortTransaction
+      end
+
+      #
+      # Persists the currently innermost transaction, meaning that its actions will be
+      # written to storage using the chosen persistence adapter.
+      # This usually happens when a #with_transaction block ends and no commit flag
+      # was set using the corresponding exception class
+      #
+      def persist_transaction
+        @stack.last.persist!
+        @stack.pop
+      end
+
+      #
+      # Wraps the given block in a petra transaction (section)
+      #
+      # @param [String] identifier
+      #   The transaction's identifier. For continued transaction it has to be
+      #   the same in each request, otherwise, a new transaction is started instead.
+      #
+      # @return [String] the transaction's identifier
+      #
+      def self.with_transaction(identifier: SecureRandom.uuid, &block)
+        within_instance do
+          Petra.logger.info "Starting transaction #{identifier}", :green
+
+          begin
+            transaction = begin_transaction(identifier)
+            yield
+          rescue Petra::Retry
+            Petra.logger.debug "Re-trying transaction #{identifier}", :blue
+            # We have to persist certain log entries before triggering a rollback
+            # as we'd lose read / write overrides otherwise
+            transaction.prepare_for_retry!
+            @stack.pop
+            retry
+          rescue Exception => error
+            handle_exception(error, transaction: transaction, &block)
+          ensure
+            # If we made it through the transaction section without raising
+            # any exception, we simply want to persist the performed transaction steps.
+            # If an exception happens during this persistence,
+            # a simple rollback is triggered as long as the transaction wasn't already persisted.
+            # TODO: See if this behaviour could cause trouble
+            unless error
+              begin
+                persist_transaction unless transaction.committed?
+              rescue Exception
+                transaction.rollback! unless transaction.persisted?
+                raise
+              end
+            end
+
+            # Remove the current transaction from the stack
+            @stack.pop
+          end
+        end
+
+        identifier
+      end
+
+      def persistence_adapter
+        @persistence_adapter ||= Petra.configuration.persistence_adapter.new
+      end
+
+      #
+      # @return [Fixnum] the number of currently active transactions
+      #
+      def transaction_count
+        @stack.size
+      end
+
+      def current_transaction
+        @stack.last
+      end
+
+      private
+
+      #
+      # Handles various exceptions which may occur during transaction execution
+      #
+      def handle_exception(error, transaction:)
+        case error
+          when Petra::Rollback
+            transaction.rollback!
+          when Petra::Reset
+            transaction.reset!
+          when Petra::ReadIntegrityError, Petra::WriteClashError
+            transaction.reset!
+            # TODO: Remove a possible continuation, we are outside of the transaction!
+            raise
+          when Petra::AbortTransaction
+            nil
+          # ActionView wraps errors inside an own error class. Therefore,
+          # we have to extract the actual exception first.
+          # TODO: Allow the registration of error handlers for certain exceptions to get rid of
+          #   this very specific behaviour in petra core
+          # TODO: There is a mechanism in petra-rails' `petra_transaction` to extract
+          #   the original exceptions. May we get rid of this now?
+          when ->(_) { Petra.rails? && error.is_a?(ActionView::Template::Error) }
+            handle_exception(error.original_exception, transaction: transaction)
+          else
+            # If another exception happened, we forward it to the actual application
+            transaction.reset!
+            raise
+        end
+      end
+
+      #
+      # Starts a new transaction and pushes it to the transaction stack.
+      # If one or more transactions are already running, a sub-transaction with a section
+      # savepoint name is started which can be rolled back individually
+      #
+      def begin_transaction(identifier)
+        Transaction.new(identifier: identifier).tap do |t|
+          @stack.push(t)
+
+          # It is important that the after_initialize method is called **after** the
+          # transaction was pushed to the transaction stack.
+          # Otherwise, +current_transaction+ might not be available for exception handling
+          # during the initialization phase.
+          t.after_initialize
+        end
+      end
+    end
+  end
+end