fixtury 0.4.1 → 1.0.0.beta1

data/lib/fixtury/locator.rb

@@ -1,48 +1,59 @@
 # frozen_string_literal: true
 
+require "fixtury/locator_backend/memory"
+
 module Fixtury
+  # Locator is responsible for recognizing, loading, and dumping references.
+  # It is a simple wrapper around a backend that is responsible for the actual work.
+  # The backend is expected to implement the following methods: recognizable_key?, recognized_value?, load_recognized_reference, dump_recognized_value.
   class Locator
 
-    class << self
-
-      attr_accessor :instance
-
-      def instance
-        @instance ||= begin
-          require "fixtury/locator_backend/memory"
-          ::Fixtury::Locator.new(
-            backend: ::Fixtury::LocatorBackend::Memory.new
-          )
-        end
-      end
-
-    end
-
     attr_reader :backend
 
-    def initialize(backend:)
+    def initialize(backend: ::Fixtury::LocatorBackend::Memory.new)
       @backend = backend
     end
 
-    def recognize?(ref)
-      raise ArgumentError, "Unable to recognize a nil ref" if ref.nil?
+    def inspect
+      "#{self.class}(backend: #{backend.class})"
+    end
+
+    # Determine if the provided locator_key is a valid form recognized by the backend.
+    #
+    # @param locator_key [Object] the locator key to check
+    # @return [Boolean] true if the locator key is recognizable by the backend
+    # @raise [ArgumentError] if the locator key is nil
+    def recognizable_key?(locator_key)
+      raise ArgumentError, "Unable to recognize a nil locator value" if locator_key.nil?
 
-      backend.recognized_reference?(ref)
+      backend.recognizable_key?(locator_key)
     end
 
-    def load(ref)
-      raise ArgumentError, "Unable to load a nil ref" if ref.nil?
+    # Load the value associated with the provided locator key.
+    #
+    # @param locator_key [Object] the locator key to load
+    # @return [Object] the loaded value
+    # @raise [ArgumentError] if the locator key is nil
+    def load(locator_key)
+      raise ArgumentError, "Unable to load a nil locator value" if locator_key.nil?
 
-      backend.load(ref)
+      backend.load(locator_key)
     end
 
-    def dump(value)
-      raise ArgumentError, "Unable to dump a nil value" if value.nil?
+    # Provide the value to the backend to generate a locator key.
+    #
+    # @param stored_value [Object] the value to dump
+    # @param context [String] a string to include in the error message if the value is nil
+    # @return [Object] the locator key
+    # @raise [ArgumentError] if the value is nil
+    # @raise [ArgumentError] if the backend is unable to dump the value
+    def dump(stored_value, context: nil)
+      raise ArgumentError, "Unable to dump a nil value. #{context}" if stored_value.nil?
 
-      ref = backend.dump(value)
-      raise ArgumentError, "The value resulted in a nil ref" if ref.nil?
+      locator_key = backend.dump(stored_value)
+      raise ArgumentError, "Dump resulted in a nil locator value. #{context}" if locator_key.nil?
 
-      ref
+      locator_key
     end
 
   end

data/lib/fixtury/locator_backend/common.rb

@@ -1,54 +1,52 @@
 # frozen_string_literal: true
 
-require "fixtury/errors/unrecognizable_locator_error"
-
 module Fixtury
   module LocatorBackend
     module Common
 
-      def recognized_reference?(_ref)
+      def recognizable_key?(_locator_value)
         raise NotImplementedError
       end
 
-      def recognized_value?(_value)
+      def recognizable_value?(_stored_value)
         raise NotImplementedError
       end
 
-      def load_recognized_reference(_ref)
+      def load_reference(_locator_value)
         raise NotImplementedError
       end
 
-      def dump_recognized_value(_value)
+      def dump_value(_stored_value)
         raise NotImplementedError
       end
 
-      def load(ref)
-        return load_recognized_reference(ref) if recognized_reference?(ref)
+      def load(locator_value)
+        return load_reference(locator_value) if recognizable_key?(locator_value)
 
-        case ref
+        case locator_value
         when Array
-          ref.map { |subref| self.load(subref) }
+          locator_value.map { |subvalue| self.load(subvalue) }
         when Hash
-          ref.each_with_object({}) do |(k, subref), h|
-            h[k] = self.load(subref)
+          locator_value.each_with_object({}) do |(k, subvalue), h|
+            h[k] = self.load(subvalue)
           end
         else
-          raise ::Fixtury::Errors::UnrecognizableLocatorError.new(:load, ref)
+          raise Errors::UnrecognizableLocatorError.new(:load, locator_value)
         end
       end
 
-      def dump(value)
-        return dump_recognized_value(value) if recognized_value?(value)
+      def dump(stored_value)
+        return dump_value(stored_value) if recognizable_value?(stored_value)
 
-        case value
+        case stored_value
         when Array
-          value.map { |subvalue| dump(subvalue) }
+          stored_value.map { |subvalue| dump(subvalue) }
         when Hash
-          ref.each_with_object({}) do |(k, subvalue), h|
+          stored_value.each_with_object({}) do |(k, subvalue), h|
             h[k] = dump(subvalue)
           end
         else
-          raise ::Fixtury::Errors::UnrecognizableLocatorError.new(:dump, value)
+          raise Errors::UnrecognizableLocatorError.new(:dump, stored_value)
         end
       end
 

data/lib/fixtury/locator_backend/globalid.rb

@@ -11,20 +11,20 @@ module Fixtury
 
       MATCHER = %r{^gid://}.freeze
 
-      def recognized_reference?(ref)
-        ref.is_a?(String) && MATCHER.match?(ref)
+      def recognizable_key?(locator_value)
+        locator_value.is_a?(String) && MATCHER.match?(locator_value)
       end
 
-      def recognized_value?(val)
-        val.respond_to?(:to_global_id)
+      def recognizable_value?(stored_value)
+        stored_value.respond_to?(:to_global_id)
       end
 
-      def load_recognized_reference(ref)
-        ::GlobalID::Locator.locate ref
+      def load_reference(locator_value)
+        ::GlobalID::Locator.locate locator_value
       end
 
-      def dump_recognized_value(value)
-        value.to_global_id.to_s
+      def dump_value(stored_value)
+        stored_value.to_global_id.to_s
       end
 
     end

data/lib/fixtury/locator_backend/memory.rb

@@ -10,16 +10,16 @@ module Fixtury
 
       MATCHER = /^fixtury-oid-(?<object_id>[\d]+)$/.freeze
 
-      def recognized_reference?(ref)
-        ref.is_a?(String) && MATCHER.match?(ref)
+      def recognizable_key?(locator_value)
+        locator_value.is_a?(String) && MATCHER.match?(locator_value)
       end
 
-      def recognized_value?(_val)
+      def recognizable_value?(_stored_value)
         true
       end
 
-      def load_recognized_reference(ref)
-        match = MATCHER.match(ref)
+      def load_reference(locator_value)
+        match = MATCHER.match(locator_value)
         return nil unless match
 
         ::ObjectSpace._id2ref(match[:object_id].to_i)
@@ -27,8 +27,8 @@ module Fixtury
         nil
       end
 
-      def dump_recognized_value(value)
-        "fixtury-oid-#{value.object_id}"
+      def dump_value(stored_value)
+        "fixtury-oid-#{stored_value.object_id}"
       end
 
     end

data/lib/fixtury/mutation_observer.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "active_support/lazy_load_hooks"
+
+module Fixtury
+  # The mutation observer class is responsible for tracking the isolation level of resources as they are created and updated.
+  # If a resource is created in one isolation level, but updated in another, the mutation observer will raise an error.
+  # If Rails is present, the Railtie will hook into ActiveRecord to automatically report these changes to the MutationObserver
+  module MutationObserver
+
+    # Hooks into the lifecycle of an ActiveRecord::Base object to report changes to the MutationObserver.
+    # This is automatically prepended to ActiveRecord::Base when Rails is present.
+    module ActiveRecordHooks
+
+      def _create_record(*args)
+        result = super
+        MutationObserver.on_record_create(self)
+        result
+      end
+
+      def _update_record(**args)
+        MutationObserver.on_record_update(self, changes)
+        super
+      end
+
+      def update_columns(changes)
+        MutationObserver.on_record_update(self, changes)
+        super
+      end
+
+    end
+
+    class << self
+
+      attr_reader :current_execution
+
+      def log(msg, level: ::Fixtury::LOG_LEVEL_DEBUG)
+        ::Fixtury.log(msg, name: "mutation_observer", level: level)
+      end
+
+      def owners
+        @owners ||= {}
+      end
+
+      def reported_owner(locator_key)
+        owners[locator_key]
+      end
+
+      # Observe mutation activity while the given block is executed.
+      #
+      # @param execution [Fixtury::Execution] The execution that is currently being observed.
+      # @yield [void] The block to execute while observing the given execution.
+      def observe(execution)
+        prev_execution = current_execution
+        @current_execution = execution
+        yield
+      ensure
+        @current_execution = prev_execution
+      end
+
+      # The isolation key of the current definition associated with the current execution.
+      #
+      # @return [String, nil] The isolation key of the current definition, or nil if there is no current definition.
+      def current_isolation_key
+        current_definition&.isolation_key
+      end
+
+      # The definition associated with the current execution.
+      #
+      # @return [Fixtury::Definition, nil] The definition associated with the current execution, or nil if there is no current execution.
+      def current_definition
+        current_execution&.definition
+      end
+
+      # Since there may be inheritance at play, we use the base class to consolidate
+      # ensure the same db record always produces the same locator key by using the
+      # base class to generate the locator key.
+      #
+      # @param obj [ActiveRecord::Base] The object to generate a locator key for.
+      # @return [String, nil] The locator key for the given object, or nil if there is no current execution.
+      def normalized_locator_key(obj)
+        return nil unless current_execution
+
+        pk = obj.class.primary_key
+        delegate_object = obj.class.base_class.new(pk => obj.read_attribute(pk))
+        current_execution.store.locator.dump(delegate_object, context: "<mutation_observer>")
+      end
+
+      # When a record is created we assign ownership to the current isolation key, if present.
+      #
+      # @param obj [ActiveRecord::Base] The record that was created.
+      # @return [void]
+      def on_record_create(obj)
+        locator_key = normalized_locator_key(obj)
+        return unless locator_key
+
+        log("Setting isolation level of #{locator_key.inspect} to #{current_isolation_key.inspect} via #{current_definition.inspect}")
+        owners[locator_key] = current_isolation_key
+      end
+
+      # When a record is updated we check to see if the reported owner matches the current isolation key.
+      # If it doesn't, we raise an error.
+      #
+      # @param obj [ActiveRecord::Base] The record that was updated.
+      # @param changes [Hash] The changes that were made to the record.
+      # @return [void]
+      # @raise [Fixtury::Errors::IsolatedMutationError] if the record is updated in a different isolation level than it was created in.
+      def on_record_update(obj, changes)
+        return if changes.blank?
+
+        locator_key = normalized_locator_key(obj)
+        log("verifying record update for #{locator_key}")
+
+        actual_owner = reported_owner(locator_key)
+        return unless actual_owner
+
+        if current_isolation_key.nil?
+          log("Allowing update to #{locator_key.inspect} because there is no registered owner.")
+          return
+        end
+
+        if actual_owner == current_isolation_key
+          log("Allowing update to #{locator_key.inspect} in the #{actual_owner.inspect} isolation level via #{current_definition.inspect}.")
+          return
+        end
+
+        raise Errors::IsolatedMutationError,  "Cannot modify #{locator_key.inspect}. Owned by: #{actual_owner.inspect}. Modified by: #{current_isolation_key.inspect}. Requested changes: #{changes.inspect}"
+      end
+
+    end
+  end
+end
+
+# Observe all executions and report changes to the MutationObserver.
+::Fixtury.hooks.around(:execution) do |execution, &block|
+  ::Fixtury::MutationObserver.observe(execution, &block)
+end
+
+# If/when activerecord loads, prepend the hooks module to ActiveRecord::Base
+ActiveSupport.on_load(:active_record) { prepend Fixtury::MutationObserver::ActiveRecordHooks }

data/lib/fixtury/path_resolver.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Fixtury
+  # Takes a namespace as context and a search string and resolves the possible
+  # absolute paths that a user could be referring to.
+  class PathResolver
+
+    attr_reader :namespace, :search
+
+    def initialize(namespace:, search:)
+      @namespace = namespace.to_s
+      @search = search.to_s
+    end
+
+    def possible_absolute_paths
+      @possible_absolute_paths ||= begin
+        out = []
+        # If the search starts with a slash it's an absolute
+        # path and it should be the only possible path.
+        if search.start_with?("/")
+          out << search
+
+        # Otherwise we need to consider the namespace.
+        else
+          # Try the namespace as a prefix for the search.
+          # This should take priority because it is the most specific.
+          out << ::File.join(namespace, search)
+
+          # In addition, someone may be referencing a path relative
+          # to root but not including the leading slash. We should
+          # consider this case as well.
+          out << ::File.join("/", search) unless search.include?(".")
+        end
+
+        # Get rid of any `.` and `..` in the paths.
+        out.map! { |path| File.expand_path(path, "/").to_s }
+        # Get rid of any duplicates.
+        out.uniq!
+        # voila
+        out
+      end
+    end
+
+  end
+end

data/lib/fixtury/railtie.rb

@@ -7,5 +7,9 @@ module Fixtury
       load "fixtury/tasks.rake"
     end
 
+    initializer "fixtury.activerecord_hooks" do
+      require "fixtury/mutation_observer"
+    end
+
   end
 end

data/lib/fixtury/reference.rb

@@ -1,29 +1,31 @@
 # frozen_string_literal: true
 
 module Fixtury
+  # Acts as an reference between the schema and an object in some remote store.
+  # The Store uses these references to keep track of the fixtures it has created.
+  # The references are used by the locator to retrieve the fixture data from whatever
+  # backend is being used.
   class Reference
 
-    HOLDER_VALUE = "__BUILDING_FIXTURE__"
+    # A special key used to indicate that the a definition is currently building an
+    # object for this locator_key. This is used to prevent circular dependencies.
+    HOLDER_KEY = "__BUILDING_FIXTURE__"
 
     def self.holder(name)
-      new(name, HOLDER_VALUE)
+      new(name, HOLDER_KEY)
     end
 
-    def self.create(name, value)
-      new(name, value)
-    end
-
-    attr_reader :name, :value, :created_at, :options
+    attr_reader :name, :locator_key, :created_at, :options
 
-    def initialize(name, value, options = {})
+    def initialize(name, locator_key, options = {})
       @name = name
-      @value = value
+      @locator_key = locator_key
       @created_at = Time.now.to_i
       @options = options
     end
 
     def holder?
-      value == HOLDER_VALUE
+      locator_key == HOLDER_KEY
     end
 
     def real?