petra_core 0.0.1

data/lib/petra/proxies/abstract_proxy.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Petra
+  module Proxies
+    class AbstractProxy
+
+      class << self
+        #
+        # Builds an ObjectProxy for the given object.
+        # If a more specific proxy class exists for the given object,
+        # it will be used instead of the generic Petra::Proxies::ObjectProxy.
+        #
+        # If there is no proxy for the exact class of the given +object+,
+        # its superclasses are automatically tested.
+        #
+        def for(object, inherited: false, **options)
+          # If the given object is configured not to use a possibly existing
+          # specialized proxy (e.g. the ActiveRecord::Base proxy), we simply
+          # build a default ObjectProxy for it, but we'll still try to extend it using
+          # available ModuleProxies
+          default_proxy = ObjectProxy.new(object, inherited, **options)
+          default_proxy.send :mixin_module_proxies!
+          return default_proxy unless inherited_config_for(object, :use_specialized_proxy)
+
+          # Otherwise, we search for a specialized proxy for the object's class
+          # and its superclasses until we either find one or reach the
+          # default ObjectProxy
+          klass = object.is_a?(Class) ? object : object.class
+          klass = klass.superclass until available_class_proxies.key?(klass.to_s)
+          proxy = available_class_proxies[klass.to_s].constantize.new(object, inherited, **options)
+
+          # If we reached Object, we might still find one or more ModuleProxy module we might
+          # mix into the resulting ObjectProxy. Otherwise, the specialized proxy will most likely
+          # have included the necessary ModuleProxies itself.
+          proxy.send(:mixin_module_proxies!) if proxy.instance_of?(Petra::Proxies::ObjectProxy)
+          proxy
+        end
+
+        #
+        # Determines the available object proxy classes and the ruby classes they
+        # can be used for. All classes in the Petra::Proxies namespace are automatically
+        # recognized as long as they define a CLASS_NAMES constant.
+        #
+        # If multiple proxies specify the same class name, the last one by sorting wins.
+        #
+        # @return [Hash] The available proxy classes in the format ("ClassName" => "ProxyClassName")
+        #
+        def available_class_proxies
+          @available_class_proxies ||= Petra::Proxies.constants.each_with_object({}) do |c, h|
+            klass = Petra::Proxies.const_get(c)
+            # Skip non-class constants (this includes modules)
+            next unless klass.is_a?(Class)
+            # Skip every class which is not an ObjectProxy. There shouldn't be any
+            # in this namespace, but you never know...
+            next unless klass <= Petra::Proxies::ObjectProxy
+            # Skip proxy classes which do not specify which classes
+            # they were built for
+            next unless klass.const_defined?(:CLASS_NAMES)
+
+            klass.const_get(:CLASS_NAMES).each { |n| h[n] = "Petra::Proxies::#{c}" }
+          end
+        end
+
+        #
+        # @see #available_class_proxies
+        #
+        # Returns only module proxies
+        #
+        def available_module_proxies
+          @available_module_proxies ||= Petra::Proxies.constants.each_with_object({}) do |c, h|
+            klass = Petra::Proxies.const_get(c)
+            next unless klass.is_a?(Module)
+            next unless klass.included_modules.include?(Petra::Proxies::ModuleProxy)
+            next unless klass.const_defined?(:MODULE_NAMES)
+
+            klass.const_get(:MODULE_NAMES).each { |n| h[n] = "Petra::Proxies::#{c}" }
+          end
+        end
+
+        #
+        # Retrieves a configuration value with the given name respecting
+        # custom configurations made for its class (or class family)
+        #
+        def inherited_config_for(object, name, *args)
+          # If the proxied object already is a class, we don't use its class (Class)
+          # as there is a high chance nobody will ever use this object proxy on
+          # this level of meta programming
+          klass = object.is_a?(Class) ? object : object.class
+          Petra.configuration.class_configurator(klass).__inherited_value(name, *args)
+        end
+      end
+
+      #
+      # As it might happen that a custom proxy has to be defined for behaviour
+      # introduced to different classes as an included module (an example would be Enumerable),
+      # it has to be possible to define an equivalent to object proxies for them.
+      # This function inspects all modules which were previously included into
+      # the proxied object's singleton class and automatically adds matching module proxies.
+      #
+      # Please take a look at Petra::Proxies::EnumerableProxy for an example module proxy
+      #
+      def mixin_module_proxies!
+        # Neither symbols nor fixnums may have singleton classes, see the corresponding Kernel method
+        return if proxied_object.is_a?(Integer) || proxied_object.is_a?(Symbol)
+
+        # Do not load ModuleProxies if the object's configuration denies it
+        return unless object_config(:mixin_module_proxies)
+
+        proxied_object.singleton_class.included_modules.each do |mod|
+          proxy_module = Petra::Proxies::ObjectProxy.available_module_proxies[mod.to_s].try(:constantize)
+          # Skip all included modules without ModuleProxies
+          next unless proxy_module
+
+          singleton_class.class_eval do
+            # Extend the proxy with the module proxy's class methods
+            extend proxy_module.const_get(:ClassMethods) if proxy_module.const_defined?(:ClassMethods)
+
+            # Include the module proxy's instance methods
+            include proxy_module.const_get(:InstanceMethods) if proxy_module.const_defined?(:InstanceMethods)
+
+            proxy_module.const_get(:INCLUDES).each { |m| include m } if proxy_module.const_defined?(:INCLUDES)
+          end
+        end
+      end
+
+      #
+      # @return [Petra::Components::Transaction] the currently active transaction
+      #
+      def transaction
+        Petra.transaction_manager.current_transaction
+      end
+
+      #
+      # @see #inherited_config_for, the proxied object is automatically passed in
+      #    as first parameter
+      #
+      def object_config(name, *args)
+        self.class.inherited_config_for(proxied_object, name, *args)
+      end
+
+      delegate :inspect, to: :proxied_object
+
+      private
+
+      def initialize; end
+
+    end
+  end
+end

data/lib/petra/proxies/enumerable_proxy.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'petra/proxies/module_proxy'
+
+module Petra
+  module Proxies
+    #
+    # Module Proxy which is used to proxy classes which include Enumerable, such as
+    # Enumerator or Array. It contains wrappers for the default enumerator functions to
+    # ensure that objects yielded to their blocks are correctly wrapped in Petra proxies (if needed)
+    #
+    module EnumerableProxy
+      include ModuleProxy
+      MODULE_NAMES = %w[Enumerable].freeze
+      INCLUDES     = [Enumerable].freeze
+
+      module InstanceMethods
+        #
+        # We have to define our own #each method for the singleton class' Enumerable
+        # It basically just wraps the original enum's entries in proxies and executes
+        # the "normal" #each
+        #
+        def each(&block)
+          Petra::Proxies::EnumerableProxy.proxy_entries(proxied_object).each(&block)
+        end
+      end
+
+      #
+      # Ensures the the objects yielded to blocks are actually petra proxies.
+      # This is necessary as the internal call to +each+ would be forwarded to the
+      # actual Enumerable object and result in unproxied objects.
+      #
+      # This method will only proxy objects which allow this through the class config
+      # as the enum's entries are seen as inherited objects.
+      # `[]` is used as method causing the proxy creation as it's closest to what's actually happening.
+      #
+      # @return [Array<Petra::Proxies::ObjectProxy>]
+      #
+      def self.proxy_entries(enum, surrogate_method: '[]')
+        enum.entries.map { |o| o.petra(inherited: true, configuration_args: [surrogate_method]) }
+      end
+    end
+  end
+end

data/lib/petra/proxies/handlers/attribute_read_handler.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Petra
+  module Proxies
+    module Handlers
+      class AttributeReadHandler < MissingMethodHandler
+        add_constraint(:before, :object_persistence)
+
+        def self.identifier
+          :attribute_read
+        end
+
+        def applicable?(method_name)
+          proxy.send(:__attribute_reader?, method_name)
+        end
+
+        def handle(method_name, *args)
+          if transaction.attribute_value?(@proxy, attribute: method_name)
+            # As we read this attribute before, we have the value we read back then on record.
+            # Therefore, we may check if the value changed in the mean time which would invalidate
+            # the transaction (most likely).
+            transaction.verify_attribute_integrity!(@proxy, attribute: method_name)
+
+            transaction.attribute_value(@proxy, attribute: method_name).tap do |result|
+              Petra.logger.debug "Served value from write set: #{method_name}  => #{result}", :yellow, :bold
+            end
+          elsif transaction.read_attribute_value?(@proxy, attribute: method_name)
+            # If we didn't write the attribute before, we may at least have already read it.
+            # In this case, we don't have to generate a new read log entry
+            transaction.verify_attribute_integrity!(@proxy, attribute: method_name)
+
+            # We also may simply return the last accepted read set value
+            transaction.read_attribute_value(@proxy, attribute: method_name).tap do |result|
+              Petra.logger.debug "Re-read attribute: #{method_name}  => #{result}", :yellow, :bold
+            end
+          else
+            proxied_object.send(method_name, *args).tap do |val|
+              transaction.log_attribute_read(@proxy, attribute: method_name, value: val, method: method_name)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/petra/proxies/handlers/missing_method_handler.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Petra
+  module Proxies
+    module Handlers
+      class MissingMethodHandler
+        def initialize(proxy)
+          @proxy = proxy
+        end
+
+        attr_reader :proxy
+        delegate :transaction, to: :@proxy
+
+        class << self
+          def constraints
+            @constraints ||= []
+          end
+
+          #
+          # Adds a constraint to this handler class regarding the position
+          # it will end up in when actually executing the handlers.
+          #
+          # @param [:before, :after, :<, :>] position
+          # @param [String, Symbol] other_handler
+          #   The other handler's identifier
+          #
+          def add_constraint(position, other_handler)
+            method = position.to_sym == :before ? :< : :>
+            constraints << [method, other_handler.to_sym]
+          end
+        end
+
+        def queue_constraints
+          not_implemented
+        end
+
+        def applicable?
+          not_implemented
+        end
+
+        def handle(*)
+          not_implemented
+        end
+      end
+    end
+  end
+end

data/lib/petra/proxies/method_handlers.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Petra
+  module Proxies
+    #
+    # This class holds method handlers for certain method groups a proxy
+    # may encounter (readers, writers, etc).
+    # They are encapsulated in an own class instead of a module mixin to keep the
+    # proxy objects as small as possible, hopefully avoiding using the same method names
+    # as a proxied object
+    #
+    class MethodHandlers
+      def initialize(proxy, proxy_binding)
+        @proxy         = proxy
+        @proxy_binding = proxy_binding
+      end
+
+      #
+      # Helper method to call private (or public) methods on the associated
+      # proxy object. It will define an own method in this class which can be used
+      # as if it would be called directly on the proxy.
+      #
+      # @param [String, Symbol] name
+      #   the method name to be called on the proxy
+      #
+      # @param [Boolean] underscore_prefix
+      #   If set to +true+, two underscores will be prefixed to the given method name, e.g.
+      #   for +__attribute_reader?+
+      #
+      def self.proxy_method(name, underscore_prefix = false)
+        define_method(name) do |*args|
+          if underscore_prefix
+            @proxy.send("__#{name}", *args)
+          else
+            @proxy.send(name, *args)
+          end
+        end
+      end
+
+      #
+      # Shortcut function to call `proxy_method` for multiple functions
+      #
+      def self.proxy_methods(*methods, underscore_prefix: false)
+        methods.each { |m| proxy_method(m, underscore_prefix) }
+      end
+
+      proxy_methods :proxied_object, :transaction, :object_config, :class_proxy?
+      proxy_methods :attribute_reader?, :type_cast_attribute_value, underscore_prefix: true
+
+      #
+      # Yields an array and executes the given handlers afterwards.
+      #
+      # @return [Object] the first handler's execution result
+      #
+      # @param [Proc, NilClass] block
+      #   As this method itself accepts a block, a proc passed to
+      #   method_missing has to be passed in in its normal parameter form
+      #
+      def execute_missing_queue(method_name, *args, block: nil)
+        yield queue = []
+        queue << :handle_missing_method if queue.empty?
+
+        send(queue.first, method_name, *args).tap do
+          queue[1..-1].each do |handler|
+            if block
+              send(handler, method_name, *args, &block)
+            else
+              send(handler, method_name, *args)
+            end
+          end
+        end
+      end
+
+      #
+      # Calls the given method on the proxied object and optionally
+      # wraps the result in another petra proxy
+      #
+      def handle_missing_method(method_name, *args, &block)
+        proxied_object
+          .public_send(method_name, *args, &block)
+          .petra(inherited: true, configuration_args: [method_name.to_s])
+      end
+
+      #
+      # A "dynamic attribute" in this case is a method which usually formats
+      # one or multiple attributes and returns the result. An example would be `#{first_name} #{last_name}`
+      # within a user class.
+      # As methods which are no simple readers/writers are usually forwarded to the proxied
+      # object, we have to make sure that these methods are called in this proxy's context, otherwise
+      # the used attribute readers would return the actual values, not the ones from our write set.
+      #
+      # There is no particularly elegant way to achieve this as all forms of bind or instance_eval/exec would
+      # not set the correct self (or be incompatible), we generate a new proc from the method's source code
+      # and call it within our own context.
+      # This should therefore be only used for dynamic attributes like the above example, more complex
+      # methods might cause serious problems.
+      #
+      def handle_dynamic_attribute_read(method_name, *args)
+        method_source_proc(method_name).call(*args)
+      end
+
+      #
+      # Logs changes made to attributes of the proxied object.
+      # This means that the attribute change is documented within the currently active transaction
+      # section and added to the temporary write set.
+      #
+      def handle_attribute_change(method_name, *args)
+        # Remove a possible "=" at the end of the setter method name
+        attribute_name = method_name
+        attribute_name = method_name[0..-2] if method_name =~ /^.*=$/
+
+        # As there might not be a corresponding getter, our fallback value for
+        # the old attribute value is +nil+. TODO: See if this causes unexpected behaviour
+        old_value      = nil
+        # To get the actual old value of an attribute reader, we have to
+        # act as if it was requested externally by either serving it from the object
+        # itself or the transaction's write set.
+        # TODO: (Better) way to determine the reader method name, it might be a different one...
+        old_value      = handle_attribute_read(attribute_name) if attribute_reader?(attribute_name)
+
+        # As we currently only handle simple setters, we expect the first given argument
+        # to be the new attribute value.
+        new_value      = args.first # type_cast_attribute_value(attribute_name, args.first)
+
+        transaction.log_attribute_change(@proxy,
+                                         attribute: attribute_name,
+                                         old_value: old_value,
+                                         new_value: new_value,
+                                         method:    method_name.to_s)
+
+        new_value
+      end
+
+      #
+      # Handles a getter method for the proxied object.
+      # As attribute changes are not actually forwarded to the actual object,
+      # we have to retrieve them from the transaction's write set.
+      #
+      def handle_attribute_read(method_name, *args)
+        # We wrote this attribute before, so we have to serve its value
+        # from the transaction's write set
+        if transaction.attribute_value?(@proxy, attribute: method_name)
+          # As we wrote this attribute before, we have the value we read back then on record.
+          # Therefore, we may check if the value changed in the mean time which would invalidate
+          # the transaction (most likely).
+          transaction.verify_attribute_integrity!(@proxy, attribute: method_name)
+
+          transaction.attribute_value(@proxy, attribute: method_name).tap do |result|
+            Petra.logger.debug "Served value from write set: #{method_name}  => #{result}", :yellow, :bold
+          end
+        elsif transaction.read_attribute_value?(@proxy, attribute: method_name)
+          # If we didn't write the attribute before, we may at least have already read it.
+          # In this case, we don't have to generate a new read log entry
+          transaction.verify_attribute_integrity!(@proxy, attribute: method_name)
+
+          # We also may simply return the last accepted read set value
+          transaction.read_attribute_value(@proxy, attribute: method_name).tap do |result|
+            Petra.logger.debug "Re-read attribute: #{method_name}  => #{result}", :yellow, :bold
+          end
+        else
+          proxied_object.send(method_name, *args).tap do |val|
+            transaction.log_attribute_read(@proxy, attribute: method_name, value: val, method: method_name)
+          end
+        end
+      end
+
+      #
+      # Handles calls to a method which persists the proxied object.
+      # As we may not actually call the method on the proxied object, we may only
+      # log the persistence.
+      #
+      # This is a very simple behaviour, so it makes sense to handle persistence methods
+      # differently in specialized object proxies (see ActiveRecordProxy)
+      #
+      # TODO: Log parameters given to the persistence method so they can be used during the commit phase
+      #
+      def handle_object_persistence(method_name, *args)
+        transaction.log_object_persistence(@proxy, method: method_name, args: args)
+        # TODO: Find a better return value for pure persistence calls
+        true
+      end
+
+      #
+      # Handles calls to a method which destroys the proxied object
+      #
+      def handle_object_destruction(method_name, *args)
+        transaction.log_object_destruction(@proxy, method: method_name, args: args)
+        true
+      end
+
+      #----------------------------------------------------------------
+      #                        Helpers
+      #----------------------------------------------------------------
+
+      #
+      # Generates a new Proc object from the source code of a given instance method
+      # of the proxied object.
+      #
+      # TODO: This does not work well with #unloadable, e.g. in Rails development environment
+      # TODO: method.parameters returns the required and optional parameters, these could be handed to the proc
+      # TODO: what happens with dynamically generated methods? is there a practical way to achieve this?
+      #
+      def method_source_proc(method_name)
+        method        = proxied_object.method(method_name.to_sym)
+        method_source = method.source.lines[1..-2].join
+        proc do
+          @proxy_binding.eval method_source
+        end
+      end
+
+    end
+  end
+end

data/lib/petra/proxies/module_proxy.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Petra
+  module Proxies
+    #
+    # Helper to mark a module inside ::Proxies as ModuleProxy.
+    # Each ModuleProxy has to include this module.
+    #
+    module ModuleProxy
+    end
+  end
+end