petra_core 0.0.1

data/lib/petra/proxies/object_proxy.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require 'petra/proxies/abstract_proxy'
+require 'petra/proxies/method_handlers'
+
+module Petra
+  module Proxies
+    #
+    # To avoid messing with the methods defined by ActiveRecord or similar,
+    # the programmer should use these proxy objects (object.petra.*) which handle
+    # actions on a different level.
+    #
+    # This class is the base proxy class which can be extended to cover
+    # certain behaviours that would be too complex to be put inside the configuration.
+    #
+    class ObjectProxy < AbstractProxy
+      include Comparable
+
+      CLASS_NAMES = %w[Object].freeze
+
+      delegate :to_s, to: :proxied_object
+
+      #
+      # Do not create new proxies for already proxied objects.
+      # Instead, return the current proxy object
+      #
+      def petra(*)
+        self
+      end
+
+      # Creepy!
+      def new(*args)
+        class_method!
+        proxied_object.new(*args).petra
+      end
+
+      #
+      # Access the proxied object publicly from each petra proxy
+      # TODO: This should not leave the proxy!
+      #
+      # @example
+      #   user = User.petra.first
+      #   user.unproxied.first_name
+      #
+      def unproxied
+        proxied_object
+      end
+
+      #
+      # Checks whether the given attribute was altered during the current transaction.
+      # Note that an attribute counts as `altered` even if it was reset to its original
+      # value in a later transaction step.
+      #
+      # @deprecated
+      #
+      # TODO: Check for dynamic attribute readers?
+      #
+      def __original_attribute?(attribute_name)
+        !transaction.attribute_value?(self, attribute: attribute_name.to_s)
+      end
+
+      #
+      # Catch all methods which are not defined on this proxy object as they
+      # are most likely meant to go to the proxied object
+      #
+      # Also checks a few special cases like attribute reads/changes.
+      # Please note that a method may be e.g. a persistence method AND an attribute writer
+      # (for normal objects, every attribute write would be persisted to memory), so
+      # we have to execute all matching handlers in a queue.
+      #
+      # rubocop:disable Style/MethodMissing
+      def method_missing(meth, *args, &block)
+        # If no transaction is currently running, we proxy everything
+        # to the original object.
+        unless Petra.transaction_running?
+          Petra.logger.info "No transaction running, proxying #{meth} to original object."
+          return unproxied.public_send(meth, *args, &block)
+        end
+
+        # As calling a superclass method in ruby does not cause method calls within this method
+        # to be called within the superclass context, the correct (= the child class') attribute
+        # detectors are run.
+        result = __handlers.execute_missing_queue(meth, *args, block: block) do |queue|
+          queue << :handle_attribute_change if __attribute_writer?(meth)
+          queue << :handle_attribute_read if __attribute_reader?(meth)
+          queue << :handle_dynamic_attribute_read if __dynamic_attribute_reader?(meth)
+          queue << :handle_object_persistence if __persistence_method?(meth)
+        end
+
+        Petra.logger.debug "#{object_class_or_self}##{meth}(#{args.map(&:inspect).join(', ')}) => #{result.inspect}"
+
+        result
+      rescue SystemStackError => e
+        exception = ArgumentError.new("Method '#{meth}' lead to a SystemStackError due to `method_missing`")
+        exception.set_backtrace(e.backtrace.uniq)
+        raise exception
+      end
+      # rubocop:enable Style/MethodMissing
+
+      #
+      # It is necessary to forward #respond_to? queries to
+      # the proxied object as otherwise certain calls, especially from
+      # the Rails framework itself will fail.
+      # Hidden methods are ignored.
+      #
+      def respond_to_missing?(meth, *)
+        proxied_object.respond_to?(meth)
+      end
+
+      #
+      # Generates an ID for the proxied object based on the class configuration.
+      # New objects (= objects which were generated within this transaction) receive
+      # an artificial ID
+      #
+      def __object_id
+        @__object_id ||= if __new?
+                           transaction.objects.next_id
+                         else
+                           object_config(:id_method, proc_expected: true, base: proxied_object)
+                         end
+      end
+
+      #
+      # Generates a unique object key based on the proxied object's class and id
+      #
+      # @return [String] the generated object key
+      #
+      def __object_key
+        [proxied_object.class, __object_id].map(&:to_s).join('/')
+      end
+
+      #
+      # Generates a unique attribute key based on the proxied object's class, id and a given attribute
+      #
+      # @param [String, Symbol] attribute
+      #
+      # @return [String] the generated attribute key
+      #
+      def __attribute_key(attribute)
+        [proxied_object.class, __object_id, attribute].map(&:to_s).join('/')
+      end
+
+      #
+      # @return [Boolean] +true+ if the proxied object did not exist before the transaction started
+      #
+      def __new?
+        transaction.objects.new?(self)
+      end
+
+      #
+      # @return [Boolean] +true+ if the proxied object existed before the transaction started
+      #
+      def __existing?
+        transaction.objects.existing?(self)
+      end
+
+      #
+      # @return [Boolean] +true+ if the proxied object was created (= initialized + persisted) during
+      #   the current transaction
+      #
+      def __created?
+        transaction.objects.created?(self)
+      end
+
+      #
+      # @return [Boolean] +true+ if the proxied object was destroyed during the transaction
+      #
+      def __destroyed?
+        transaction.objects.destroyed?(self)
+      end
+
+      #
+      # Very simple spaceship operator based on the object key
+      # TODO: See if this causes problems when ID-ordering is expected.
+      #   For existing objects that shouldn't be the case in most situations as
+      #   a collection mostly contains only objects of one kind
+      #
+      def <=>(other)
+        __object_key <=> other.__object_key
+      end
+
+      protected
+
+      #----------------------------------------------------------------
+      #                    Method Group Detectors
+      #----------------------------------------------------------------
+
+      #
+      # Checks whether the given method name is part of the configured attribute reader
+      # methods within the currently proxied class
+      #
+      def __attribute_reader?(method_name)
+        object_config(:attribute_reader?, method_name.to_s)
+      end
+
+      #
+      # @see #attribute_reader?
+      #
+      def __attribute_writer?(method_name)
+        object_config(:attribute_writer?, method_name.to_s)
+      end
+
+      #
+      # @see #attribute_reader?
+      #
+      # Currently, classes may not use dynamic attribute readers
+      #
+      def __dynamic_attribute_reader?(method_name)
+        !class_proxy? && object_config(:dynamic_attribute_reader?, method_name.to_s)
+      end
+
+      #
+      # @return [Boolean] +true+ if the given method would persist the
+      #   proxied object
+      #
+      def __persistence_method?(method_name)
+        !class_proxy? && object_config(:persistence_method?, method_name.to_s)
+      end
+
+      #
+      # @return [Boolean] +true+ if the given method name is a "destructor" of the
+      #   proxied object
+      #
+      def __destruction_method?(method_name)
+        !class_proxy? && object_config(:destruction_method?, method_name.to_s)
+      end
+
+      #
+      # Sets the given attribute to the given value using the default setter
+      # function `name=`. This function is just a convenience method and does not
+      # manage the actual write set. Please take a look at #handle_attribute_change instead.
+      #
+      # @param [String, Symbol] attribute
+      #   The attribute name. The proxied object is expected to have a corresponding public setter method
+      #
+      # @param [Object] new_value
+      #
+      def __set_attribute(attribute, new_value)
+        public_send("#{attribute}=", new_value)
+      end
+
+      def __handlers
+        @__handlers ||= Petra::Proxies::MethodHandlers.new(self, binding)
+      end
+
+      def initialize(object, inherited = false, object_id: nil)
+        @obj         = object
+        @inherited   = inherited
+        @__object_id = object_id
+      end
+
+      #
+      # @return [Object] the proxied object
+      #
+      def proxied_object
+        @obj
+      end
+
+      #
+      # @return [Boolean] +true+ if the proxied object is a class
+      #
+      def class_proxy?
+        proxied_object.is_a?(Class)
+      end
+
+      #
+      # @return [Class] the proxied object if it is a class itself, otherwise
+      #   the proxied object's class.
+      #
+      def object_class_or_self
+        class_proxy? ? proxied_object : proxied_object.class
+      end
+
+      #
+      # @return [Boolean] +true+ if the proxied object is a +klass+
+      #
+      def for_class?(klass)
+        proxied_object.is_a?(klass)
+      end
+
+      #
+      # Performs possible type casts on a value which is about to be set
+      # for an attribute. For general ObjectProxy instances, this is simply the identity
+      # function, but it might be overridden in more specialized proxies.
+      #
+      def __type_cast_attribute_value(_attribute, value)
+        value
+      end
+
+      #
+      # Raises an exception if proxied object isn't a class.
+      # Currently, there is no way to specify which methods are class and instance methods
+      # in a specialized proxy, so this at least tells the developer that he did something wrong.
+      #
+      def class_method!
+        return if class_proxy?
+        fail Petra::PetraError, 'This method is meant to be used as a singleton method, not an instance method.'
+      end
+
+      #
+      # @see #class_method!
+      #
+      def instance_method!
+        return if class_proxy?
+        fail Petra::PetraError, 'This method is meant to be used as an instance method only!'
+      end
+
+    end
+  end
+end

data/lib/petra/util/debug.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Petra
+  module Util
+    module Debug
+      STRING_COLORS = {light_gray: 90,
+                       yellow: 33,
+                       green: 32,
+                       red: 31,
+                       purple: 35,
+                       cyan: 36,
+                       blue: 34}.freeze
+
+      FORMATS = {default: 0,
+                 bold: 1,
+                 underline: 4}.freeze
+
+      %i[debug info warn error].each do |level|
+        define_method level do |message, color = :light_gray, format = :default|
+          log(message, level: level, color: color, format: format)
+        end
+
+        module_function level
+      end
+
+      def log(message, level: :debug, color: :light_gray, format: :default)
+        logger.send(level, 'Petra :: ' + colored_string(message, color, format))
+      end
+
+      private
+
+      def logger
+        @logger ||= Logger.new(STDOUT).tap do |l|
+          l.level = "Logger::#{Petra.configuration.log_level.upcase}".constantize
+        end
+      end
+
+      def colored_string(string, color, format)
+        "\e[#{Petra::Util::Debug::FORMATS[format]};#{Petra::Util::Debug::STRING_COLORS[color.to_sym]}m#{string}\e[0m"
+      end
+
+      module_function :log, :logger, :colored_string
+    end
+  end
+end

data/lib/petra/util/extended_attribute_accessors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Petra
+  module Util
+    module ExtendedAttributeAccessors
+      extend ActiveSupport::Concern
+
+      included do
+        extend ClassMethods
+      end
+
+      module ClassMethods
+        # TODO: Keep track of available accessors on class level
+        # TODO: Keep track of the actual values on instance (or class instance) level
+
+        def extended_attr_accessor(name, **options)
+          singleton = options.fetch(:singleton, false)
+          methods_method, definer_method = :instance_methods, :define_method
+          methods_method, definer_method = :singleton_methods, :define_singleton_method if singleton
+
+          unless send(methods_method).include?(:extended_attribute_accessors)
+            send(definer_method, :__extended_attribute_accessors__) do |group = :general|
+              (@extended_attribute_accessors ||= {})[group.to_sym] ||= {}
+            end
+
+            send(definer_method, :extended_attribute_accessors) do |group = :general, only: nil|
+              result = __extended_attribute_accessors__(group)
+              return result unless only
+
+              result.each_with_object({}) do |(k, v), h|
+                h[k] = v.slice(Array(only).map(:to_sym))
+              end
+            end
+          end
+
+          group = options.fetch(:group, :general)
+
+          send(definer_method, name) do
+            accessor = extended_attribute_accessors(group)[name.to_sym] || {}
+            accessor[:value] || accessor[:default]
+          end
+
+          define_method("#{name}=") do |value|
+            self[name] = value
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/petra/util/field_accessors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Petra
+  module Util
+    module FieldAccessors
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def field_accessor(name)
+          define_method(name) do
+            self[name]
+          end
+
+          define_method("#{name}=") do |value|
+            self[name] = value
+          end
+        end
+      end
+
+      def fields
+        @fields ||= {}
+      end
+
+      def [](key)
+        fields[key.to_s]
+      end
+
+      def []=(key, value)
+        fields[key.to_s] = value
+      end
+    end
+  end
+end

data/lib/petra/util/registrable.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Petra
+  module Util
+    #
+    # Helper module to add register functionality to a class
+    # This means that other classes may register themselves under a certain name
+    #
+    module Registrable
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        #
+        # Generates helper methods from the given name.
+        #
+        # @example Type register
+        #   acts_as_register(:type)
+        #   => registered_types
+        #   => register_type(type)
+        #   => registered_type(type) #=> value
+        #   => registered_type?(type) #=> true/false
+        #
+        def acts_as_register(name)
+          name = name.to_s
+
+          define_singleton_method("registered_#{name.pluralize}") do
+            @registered_components ||= {}
+            @registered_components[name.to_s] ||= {}
+          end
+
+          define_singleton_method("registered_#{name}") do |key|
+            send("registered_#{name.pluralize}")[key.to_s]
+          end
+
+          define_singleton_method("register_#{name}") do |key, value|
+            send("registered_#{name.pluralize}")[key.to_s] = value
+          end
+
+          define_singleton_method("registered_#{name}?") do |key|
+            send("registered_#{name.pluralize}").key?(key.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/petra/util/test_helpers.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Petra
+  module Util
+    module TestHelpers
+
+    end
+  end
+end

data/lib/petra/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Petra
+  VERSION = '0.0.1'
+end

data/lib/petra.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'active_support/all'
+require 'method_source'
+require 'pathname'
+
+require 'petra/core_ext'
+require 'petra/exceptions'
+require 'petra/configuration/base'
+require 'petra/configuration/class_configurator'
+require 'petra/util/debug'
+require 'petra/persistence_adapters/file_adapter'
+
+require 'petra/proxies/enumerable_proxy'
+require 'petra/proxies/object_proxy'
+
+require 'petra/components/transaction_manager'
+
+require 'petra/components/entries/attribute_change'
+require 'petra/components/entries/attribute_change_veto'
+require 'petra/components/entries/attribute_read'
+require 'petra/components/entries/object_destruction'
+require 'petra/components/entries/object_initialization'
+require 'petra/components/entries/object_persistence'
+require 'petra/components/entries/read_integrity_override'
+
+require 'forwardable'
+
+module Petra
+  extend SingleForwardable
+
+  def self.root
+    Pathname.new(File.dirname(__FILE__))
+  end
+
+  #
+  # @return [Petra::Configuration::Base] petra's configuration instance
+  #
+  def self.configuration
+    @configuration ||= Petra::Configuration::Base.new
+  end
+
+  #
+  # Executes the given block in the context of petra's configuration instance
+  #
+  def self.configure(&proc)
+    configuration.instance_eval(&proc) if block_given?
+  end
+
+  #
+  # Forward transaction handling to the TransactionManager class
+  #
+  # @see Petra::Components::TransactionManager#with_transaction
+  #
+  def self.transaction(identifier: nil, &block)
+    Petra::Components::TransactionManager.with_transaction(identifier: identifier || SecureRandom.uuid, &block)
+  end
+
+  #
+  # @return [Boolean] +true+ if a transaction is currently running
+  #
+  def self.transaction_running?
+    Petra::Components::TransactionManager.instance?
+  end
+
+  #
+  # Attempts to commit the currently active transaction
+  #
+  def self.commit!
+    transaction_manager.commit_transaction
+  end
+
+  #
+  # @return [Petra::Components::TransactionManager, NilClass]
+  #
+  def self.transaction_manager
+    Petra::Components::TransactionManager.instance
+  end
+
+  def_delegator :transaction_manager, :current_transaction
+
+  #
+  # Logs the given +message+
+  #
+  def self.logger
+    Petra::Util::Debug
+  end
+
+  def self.rails?
+    defined?(Rails)
+  end
+end
+
+# Extend the Object class to add the `petra` proxy generator
+Object.class_eval do
+  include Petra::CoreExt::Object
+end
+
+# Register Persistence Adapters
+Petra::PersistenceAdapters::Adapter.register_adapter(:file, Petra::PersistenceAdapters::FileAdapter)

data/lib/tasks/petra_tasks.rake

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+# desc "Explaining what the task does"
+# task :petra do
+#   # Task goes here
+# end

data/petra.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'petra/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'petra_core'
+  spec.version       = Petra::VERSION
+  spec.authors       = ['Stefan Exner']
+  spec.email         = ['stex@sterex.de']
+
+  spec.summary       = 'Proof-Of-Concept for temporarily persisted transactions in Ruby'
+  spec.homepage      = 'https://github.com/stex/petra'
+  spec.license       = 'MIT'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '~> 2.5'
+
+  spec.add_dependency 'activesupport', '~> 4.2'
+  spec.add_dependency 'method_source', '~> 0.9.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'faker', '~> 1.8'
+  spec.add_development_dependency 'pry', '~> 0.11'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 0.53.0'
+end