petra_core 0.0.1

data/lib/petra/exceptions.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Petra
+
+  #----------------------------------------------------------------
+  #                     Exception Base classes
+  #----------------------------------------------------------------
+
+  # Generic error class wrapping all custom petra exceptions
+  class PetraError < StandardError
+  end
+
+  #
+  # Error class which accepts an options hash and sets its key/value pairs
+  # as instance variables. Inherited classes therefore only have to specify the
+  # corresponding attribute readers
+  #
+  class ExtendedError < PetraError
+    def initialize(**options)
+      options.each do |k, v|
+        instance_variable_set("@#{k}", v)
+      end
+    end
+  end
+
+  # Used whenever a configuration value differs from what petra expects it to be
+  class ConfigurationError < PetraError
+  end
+
+  # Used for generic errors during transaction persistence
+  class PersistenceError < PetraError
+  end
+
+  # Thrown when a transaction should be persisted, but is locked by another instance
+  class TransactionLocked < PetraError
+  end
+
+  class HandlerException < ExtendedError
+
+    def retry!
+      fail Petra::Retry
+    end
+
+    #
+    # Resets the currently active transaction
+    # This will stop the transaction execution, so make sure that you wrap
+    # important code which has to be executed afterwards in an `ensure`
+    #
+    def reset_transaction!
+      @reset = true
+      Petra.transaction_manager.reset_transaction
+    end
+
+    #
+    # Requests a section rollback on the currently active transaction
+    # This will stop the transaction execution, so make sure that you wrap
+    # important code which has to be executed afterwards in an `ensure`
+    #
+    def rollback_transaction!
+      @rollback = true
+      Petra.transaction_manager.rollback_transaction
+    end
+
+    alias rollback! rollback_transaction!
+    alias reset! reset_transaction!
+
+    def continue!
+      fail Petra::ContinuationError, 'The transaction processing cannot be resumed.' unless continuable?
+      @continuation.call
+    end
+
+    def continuable?
+      false
+    end
+
+    protected
+
+    def continuation?
+      !!@continuation
+    end
+  end
+
+  class ValueComparisonError < HandlerException
+    attr_reader :object # The affected proxy
+    attr_reader :attribute # The affected attribute
+    attr_reader :external_value # The new external attribute value
+
+    #
+    # Tells the current transaction to ignore further errors of this kind
+    # until the attribute value is changed again externally.
+    #
+    # @param [Boolean] update_value
+    #   If set to +true+, the read set entry for this attribute is updated with the
+    #   new external value. This means that the new value will be visible inside of
+    #   the transaction until it changes again.
+    #
+    #   Otherwise, the exception is completely ignored and will have no impact
+    #   on the values displayed inside the transaction.
+    #
+    def ignore!(update_value: false)
+      Petra.current_transaction.current_section.log_read_integrity_override(object,
+                                                                            attribute:      attribute,
+                                                                            external_value: external_value,
+                                                                            update_value:   update_value)
+    end
+
+    def continuable?
+      !@reset && !@rollback
+    end
+  end
+
+  # Thrown when a read attribute changed its value externally
+  # If we read AND changed the attribute, a ReadWriteIntegrityError is raised instead
+  class ReadIntegrityError < ValueComparisonError
+    attr_reader :last_read_value # The value we last read for this attribute (before it was changed)
+  end
+
+  # Thrown when an attribute that we previously read AND changed
+  # was also changed externally.
+  class WriteClashError < ValueComparisonError
+    attr_reader :our_value
+
+    #
+    # Tells the transaction to ignore all changes previously done to the current
+    # attribute in the transaction.
+    #
+    def undo_changes!
+      Petra.current_transaction.current_section.log_attribute_change_veto(object,
+                                                                          attribute:      attribute,
+                                                                          external_value: external_value)
+    end
+
+    alias their_value external_value
+    alias use_ours! ignore!
+    alias use_theirs! undo_changes!
+  end
+
+  #----------------------------------------------------------------
+  #                  Transaction Flow Error Classes
+  #----------------------------------------------------------------
+
+  # Used internally when a lock could not be acquired (non-suspending locking)
+  class LockError < HandlerException
+    attr_reader :lock_type
+    attr_reader :lock_name
+
+    def initialize(lock_type: 'general', lock_name: 'general', processed: false)
+      @lock_type = lock_type
+      @lock_name = lock_name
+      @processed = processed
+    end
+
+    def processed?
+      @processed
+    end
+  end
+
+  class ControlFlowException < PetraError
+  end
+
+  # This error is thrown only to tell the transaction manager to
+  # abort the current transaction's execution.
+  # This is necessary e.g. after successfully committing a transaction
+  class AbortTransaction < ControlFlowException
+  end
+
+  # An error class which is never passed on out of petra.
+  # It is used to cause a rollback for the currently active petra transaction
+  class Rollback < ControlFlowException
+  end
+
+  # See +Rollback+, this error class is used to trigger a complete
+  # reset on the currently active petra transaction
+  # TODO: Nested transactions anyone?
+  class Reset < ControlFlowException
+  end
+
+  class Retry < ControlFlowException
+  end
+
+end

data/lib/petra/persistence_adapters/adapter.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'petra/util/registrable'
+
+module Petra
+  module PersistenceAdapters
+    # rubocop:disable Lint/UnusedMethodArgument
+
+    #
+    # This class acts as an interface and specifies the methods that
+    # a transaction adapter has to implement.
+    #
+    class Adapter
+      include Petra::Util::Registrable
+      acts_as_register :adapter
+
+      class << self
+        alias [] registered_adapter
+      end
+
+      #
+      # @abstract
+      #
+      # Persists the transaction steps which happened after
+      # the last changes were persisted.
+      #
+      def persist!
+        not_implemented
+      end
+
+      #
+      # Adds the given log entry to the queue to be persisted next.
+      # Fails if the queue already contains the log entry.
+      #
+      # @param [Petra::Components::LogEntry] log_entry
+      #
+      def enqueue(log_entry)
+        if queue.include?(log_entry)
+          fail Petra::PersistenceError, 'A log entry can only be added to a persistence queue once'
+        end
+        queue << log_entry
+      end
+
+      #
+      # @abstract
+      #
+      # @return [Array<String>] the identifiers of all transactions which are
+      #   currently persisted (>= one section finished, but not committed)
+      #
+      def transaction_identifiers
+        not_implemented
+      end
+
+      #
+      # @abstract
+      #
+      # @param [Petra::Components::Transaction] _transaction
+      #
+      # @return [Array<String>] the names of all savepoints which were previously persisted
+      #   for the given transaction
+      #
+      def savepoints(_transaction)
+        not_implemented
+      end
+
+      #
+      # @abstract
+      #
+      # @param [Petra::Components::Section] _section
+      #
+      # @return [Array<Petra::Components::LogEntry>] All log entries which were previously
+      #   persisted for the given section
+      #
+      def log_entries(_section)
+        not_implemented
+      end
+
+      #
+      # Resets the given transaction, meaning that all persisted information is removed
+      #
+      def reset_transaction(_transaction)
+        not_implemented
+      end
+
+      #
+      # @abstract
+      #
+      # Executes the given block after acquiring a global lock
+      #
+      # The actual implementation must ensure that an acquired lock is released in case of
+      # an exception!
+      #
+      # @param [Boolean] suspend
+      #   If set to +false+, the method will not suspend if the global lock could not be
+      #   acquired. Instead, a Petra::LockError is thrown
+      #
+      # @raise [Petra::LockError] see +suspend+
+      #
+      def with_global_lock(suspend: true)
+        not_implemented
+      end
+
+      #
+      # @abstract
+      #
+      # Executes the given block after acquiring a transaction based lock,
+      # meaning that other processes which execute something in the same transaction's context
+      # have to wait / abort
+      #
+      # The actual implementation must ensure that an acquired lock is released in case of
+      # an exception!
+      #
+      # @param [Boolean] suspend
+      #   If set to +false+, the method will not suspend if the transaction lock could not be
+      #   acquired. Instead, a Petra::LockError is thrown
+      #
+      # @raise [Petra::LockError] see +suspend+
+      #
+      def with_transaction_lock(_identifier, suspend: true)
+        not_implemented
+      end
+
+      #
+      # @abstract
+      #
+      # Executes the given block after acquiring the lock for the given proxy (object)
+      #
+      # The actual implementation must ensure that an acquired lock is released in case of
+      # an exception!
+      #
+      # @param [Petra::Proxies::ObjectProxy] _proxy
+      #
+      # @param [Boolean] suspend
+      #   See #with_global_lock
+      #
+      # @raise [Petra::LockError]
+      #
+      def with_object_lock(_proxy, suspend: true)
+        not_implemented
+      end
+
+      protected
+
+      def queue
+        @queue ||= []
+      end
+
+      def clear_queue!
+        @queue = []
+      end
+    end
+    # rubocop:enable Lint/UnusedMethodArgument
+  end
+end

data/lib/petra/persistence_adapters/file_adapter.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require 'petra/persistence_adapters/adapter'
+require 'yaml'
+
+module Petra
+  module PersistenceAdapters
+    class FileAdapter < Adapter
+
+      #----------------------------------------------------------------
+      #                        Configuration
+      #----------------------------------------------------------------
+
+      # TODO: change this to use e.g. the field accessors
+      class << self
+        def storage_directory
+          ::Pathname.new(@storage_directory || '/tmp/petra')
+        end
+
+        attr_writer :storage_directory
+      end
+
+      def persist!
+        return true if queue.empty?
+
+        # rubocop:disable Style/WhileUntilDo
+        # We currently only allow entries for one transaction in the queue
+        with_transaction_lock(queue.first.transaction_identifier) do
+          while (entry = queue.shift) do
+            identifier = create_entry_file(entry)
+            entry.mark_as_persisted!(identifier)
+          end
+        end
+        # rubocop:enable Style/WhileUntilDo
+      end
+
+      def transaction_identifiers
+        # Wait until no other transaction is doing stuff that might lead to inconsistent data
+        with_global_lock do
+          ensure_directory_existence('transactions')
+          storage_file_name('transactions').children.select(&:directory?).map(&:basename).map(&:to_s)
+        end
+      end
+
+      def savepoints(transaction)
+        with_transaction_lock(transaction.identifier) do
+          return [] unless File.exist? storage_file_name('transactions', transaction.identifier)
+          storage_file_name('transactions', transaction.identifier).children.select(&:directory?).map do |f|
+            ::YAML.load_file(f.join('information.yml').to_s)[:savepoint]
+          end
+        end
+      end
+
+      def log_entries(section)
+        with_transaction_lock(section.transaction.identifier) do
+          section_dir = storage_file_name(*section_dirname(section))
+
+          # If the given section has never been persisted before, we don't have to
+          # search further for log entries
+          return [] unless section_dir.exist?
+
+          section_dir.children.select { |f| f.extname == '.entry' }.map do |f|
+            entry_hash = ::YAML.load_file(f.to_s)
+            Petra::Components::LogEntry.from_hash(section, entry_hash)
+          end
+        end
+      end
+
+      #
+      # Removes everything that was persisted while executing the given transaction
+      #
+      def reset_transaction(transaction)
+        with_transaction_lock(transaction) do
+          if storage_file_name('transactions', transaction.identifier).exist?
+            FileUtils.rm_r(storage_file_name('transactions', transaction.identifier))
+          end
+        end
+      end
+
+      def with_global_lock(**options, &block)
+        with_file_lock('global.persistence', **options, &block)
+      rescue Petra::LockError => e
+        raise e if e.processed?
+        exception = Petra::LockError.new(lock_type: 'global', lock_name: 'global.persistence', processed: true)
+        raise exception, 'The global lock could not be acquired.'
+      end
+
+      def with_transaction_lock(transaction, **options, &block)
+        identifier = transaction.is_a?(Petra::Components::Transaction) ? transaction.identifier : transaction
+        with_file_lock("transaction.#{identifier}", **options, &block)
+      rescue Petra::LockError => e
+        raise e if e.processed?
+        exception = Petra::LockError.new(lock_type: 'transaction', lock_name: identifier, processed: true)
+        raise exception, "The transaction lock '#{identifier}' could not be acquired."
+      end
+
+      def with_object_lock(proxy, **options, &block)
+        key = proxy.__object_key.gsub(/[^a-zA-Z0-9]/, '-')
+        with_file_lock("proxy.#{key}", **options, &block)
+      rescue Petra::LockError => e
+        raise e if e.processed?
+        exception = Petra::LockError.new(lock_type: 'object', lock_name: proxy.__object_key, processed: true)
+        raise exception, "The object lock '#{proxy.__object_id}' could not be acquired."
+      end
+
+      private
+
+      #
+      # The Ruby version of `mkdir -p`
+      #
+      # @param [*Array] path
+      #   The path to the directory in a format #storage_file_name understands
+      #
+      def ensure_directory_existence(*path)
+        FileUtils.mkdir_p(storage_file_name(*path))
+      end
+
+      #
+      # Executes the given block after acquiring a lock on the given filename
+      # If the lock is already held by this process, but not with the same file handle,
+      # the function will not try to acquire it again.
+      #
+      # @param [String] filename
+      #
+      # @param [Boolean] suspend
+      #   If set to +false+, a LockError is thrown if the lock could not be acquired.
+      #
+      # @raise [Petra::LockError] If +suspend+ is set to +false+ and the lock could not be acquired
+      #
+      # TODO: sanitize file names
+      #
+      def with_file_lock(filename, suspend: true)
+        Thread.current[:__petra_file_locks] ||= []
+        lock_held = Thread.current[:__petra_file_locks].include?(lock_file_name(filename).to_s)
+
+        return yield if lock_held
+
+        File.open(lock_file_name(filename), File::RDWR | File::CREAT, 0o644) do |f|
+          if suspend
+            f.flock(File::LOCK_EX)
+          else
+            unless f.flock(File::LOCK_EX | File::LOCK_NB)
+              Petra.logger.debug "#{Thread.current.name}: Could not acquire '#{filename}'", :red
+              fail Petra::LockError
+            end
+          end
+
+          Petra.logger.debug "#{Thread.current.name}: Acquired Lock: #{filename}", :purple
+
+          Thread.current[:__petra_file_locks] << lock_file_name(filename).to_s
+
+          begin
+            yield
+          ensure
+            # Should be done automatically when the file handle is closed, but who knows
+            f.flock(File::LOCK_UN)
+            Petra.logger.debug "#{Thread.current.name}: Released Lock: #{filename}", :cyan
+            Thread.current[:__petra_file_locks].delete(lock_file_name(filename).to_s)
+          end
+        end
+      end
+
+      #
+      # Builds the path to a given file based on the configured storage directory
+      #
+      # @example STORAGE_DIR/oompa/loompa
+      #   storage_file_name('oompa', 'loompa')
+      #
+      def storage_file_name(*parts)
+        self.class.storage_directory.join(*parts)
+      end
+
+      #
+      # @param [String] filename
+      #
+      # @return [String] the path to a lockfile with the given name
+      #
+      def lock_file_name(filename)
+        # Make sure the locks directory actually exists
+        ensure_directory_existence('locks')
+        storage_file_name('locks', "petra.#{filename}.lock")
+      end
+
+      #
+      # Opens a file within the storage directory and yields its handle
+      #
+      def with_storage_file(*parts, mode: 'r', perm: 0o644, &block)
+        File.open(storage_file_name(*parts), mode, perm, &block)
+      end
+
+      #
+      # Creates a directory for the given section.
+      # This includes an `information.yml` file within the directory
+      # which contains information about the current savepoint and transaction
+      #
+      # @param [Petra::Components::Section] section
+      #
+      def add_section_directory(section)
+        dir = section_dirname(section)
+        ensure_directory_existence(*dir)
+
+        # If there is already a section directory/information file, we are done.
+        return if storage_file_name(*dir, 'information.yml').exist?
+
+        section_hash = {transaction_identifier: section.transaction.identifier,
+                        savepoint:              section.savepoint,
+                        savepoint_version:      section.savepoint_version}
+        with_storage_file(*dir, 'information.yml', mode: 'w') do |f|
+          ::YAML.dump(section_hash, f)
+        end
+      end
+
+      #
+      # Creates a file for the given LogEntry.
+      # It contains the necessary information to deserialize it later.
+      #
+      # These files are placed within a section directory (/transaction/section/entry)
+      #
+      # @param [Petra::Components::LogEntry] entry
+      #
+      def create_entry_file(entry)
+        add_section_directory(entry.section)
+        t = Time.now
+        filename = "#{t.to_i}.#{t.nsec}.entry"
+        with_storage_file(*section_dirname(entry.section), filename, mode: 'w') do |f|
+          ::YAML.dump(entry.to_h(entry_identifier: filename), f)
+        end
+        filename
+      end
+
+      #
+      # @return [Array<String>] The directory name components for the given section within STORAGE_DIR
+      #
+      def section_dirname(section)
+        ['transactions', section.transaction.identifier, section.savepoint_version.to_s]
+      end
+    end
+  end
+end