samvera-nesting_indexer 0.3.0

data/lib/samvera/nesting_indexer/adapters/abstract_adapter.rb

@@ -0,0 +1,44 @@
+module Samvera
+  module NestingIndexer
+    module Adapters
+      # @api public
+      # A module that defines the interface of methods required to interact with Samvera::NestingIndexer operations
+      # rubocop:disable Lint/UnusedMethodArgument
+      module AbstractAdapter
+        # @api public
+        # @param id [String]
+        # @return Samvera::NestingIndexer::Document::PreservationDocument
+        def self.find_preservation_document_by(id:)
+          raise NotImplementedError
+        end
+
+        # @api public
+        # @param id [String]
+        # @return Samvera::NestingIndexer::Documents::IndexDocument
+        def self.find_index_document_by(id:)
+          raise NotImplementedError
+        end
+
+        # @api public
+        # @yield Samvera::NestingIndexer::Document::PreservationDocument
+        def self.each_preservation_document(&block)
+          raise NotImplementedError
+        end
+
+        # @api public
+        # @param document [Samvera::NestingIndexer::Documents::IndexDocument]
+        # @yield Samvera::NestingIndexer::Documents::IndexDocument
+        def self.each_child_document_of(document:, &block)
+          raise NotImplementedError
+        end
+
+        # @api public
+        # @return Hash - the attributes written to the indexing layer
+        def self.write_document_attributes_to_index_layer(attributes = {})
+          raise NotImplementedError
+        end
+      end
+      # rubocop:enable Lint/UnusedMethodArgument
+    end
+  end
+end

data/lib/samvera/nesting_indexer/adapters/in_memory_adapter.rb

@@ -0,0 +1,157 @@
+require 'samvera/nesting_indexer/adapters/abstract_adapter'
+require 'samvera/nesting_indexer/documents'
+
+module Samvera
+  module NestingIndexer
+    module Adapters
+      # @api public
+      #
+      # Defines the interface for interacting with the InMemory layer. It is a reference
+      # implementation that is used throughout tests.
+      module InMemoryAdapter
+        extend AbstractAdapter
+        # @api public
+        # @param id [String]
+        # @return Samvera::NestingIndexer::Document::PreservationDocument
+        def self.find_preservation_document_by(id:)
+          Preservation.find(id)
+        end
+
+        # @api public
+        # @param id [String]
+        # @return Samvera::NestingIndexer::Documents::IndexDocument
+        def self.find_index_document_by(id:)
+          Index.find(id)
+        end
+
+        # @api public
+        # @yield Samvera::NestingIndexer::Document::PreservationDocument
+        def self.each_preservation_document(&block)
+          Preservation.find_each { |document| yield(document) }
+        end
+
+        # @api public
+        # @param document [Samvera::NestingIndexer::Documents::IndexDocument]
+        # @yield Samvera::NestingIndexer::Documents::IndexDocument
+        def self.each_child_document_of(document:, &block)
+          Index.each_child_document_of(document: document, &block)
+        end
+
+        # @api public
+        # This is not something that I envision using in the production environment;
+        # It is hear to keep the Preservation system isolated and accessible only through interfaces.
+        # @return Samvera::NestingIndexer::Documents::PreservationDocument
+        def self.write_document_attributes_to_preservation_layer(attributes = {})
+          Preservation.write_document(attributes)
+        end
+
+        # @api public
+        # @return Hash - the attributes written to the indexing layer
+        def self.write_document_attributes_to_index_layer(attributes = {})
+          Index.write_document(attributes)
+        end
+
+        # @api private
+        def self.clear_cache!
+          Preservation.clear_cache!
+          Index.clear_cache!
+        end
+
+        # @api private
+        #
+        # A module mixin to expose rudimentary read/write capabilities
+        #
+        # @example
+        #   module Foo
+        #     extend Samvera::NestingIndexer::StorageModule
+        #   end
+        module StorageModule
+          def write(doc)
+            cache[doc.id] = doc
+          end
+
+          def find(id)
+            cache.fetch(id.to_s)
+          end
+
+          def find_each
+            cache.each { |_key, document| yield(document) }
+          end
+
+          def clear_cache!
+            @cache = {}
+          end
+
+          def cache
+            @cache ||= {}
+          end
+          private :cache
+        end
+
+        # @api private
+        #
+        # A module responsible for containing the "preservation interface" logic.
+        # In the case of CurateND, there will need to be an adapter to get a Fedora
+        # object coerced into a Samvera::NestingIndexer::Preservation::Document
+        module Preservation
+          def self.find(id, *)
+            MemoryStorage.find(id)
+          end
+
+          def self.find_each(*, &block)
+            MemoryStorage.find_each(&block)
+          end
+
+          def self.clear_cache!
+            MemoryStorage.clear_cache!
+          end
+
+          def self.write_document(attributes = {})
+            Documents::PreservationDocument.new(attributes).tap do |doc|
+              MemoryStorage.write(doc)
+            end
+          end
+
+          # :nodoc:
+          module MemoryStorage
+            extend StorageModule
+          end
+          private_constant :MemoryStorage
+        end
+        private_constant :Preservation
+
+        # @api private
+        #
+        # An abstract representation of the underlying index service. In the case of
+        # CurateND this is an abstraction of Solr.
+        module Index
+          def self.clear_cache!
+            Storage.clear_cache!
+          end
+
+          def self.find(id)
+            Storage.find(id)
+          end
+
+          def self.each_child_document_of(document:, &block)
+            Storage.find_children_of_id(document.id).each(&block)
+          end
+
+          def self.write_document(attributes = {})
+            Documents::IndexDocument.new(attributes).tap { |doc| Storage.write(doc) }
+          end
+
+          # :nodoc:
+          module Storage
+            extend StorageModule
+            def self.find_children_of_id(id)
+              cache.values.select { |document| document.parent_ids.include?(id) }
+            end
+          end
+          private_constant :Storage
+        end
+        private_constant :Index
+      end
+    end
+  end
+end

data/lib/samvera/nesting_indexer/adapters/interface_behavior_spec.rb

@@ -0,0 +1,53 @@
+if defined?(RSpec)
+  RSpec.shared_examples 'a Samvera::NestingIndexer::Adapter' do
+    let(:required_parameters_extractor) { ->(method) { method.parameters.select { |type, kwarg| type == :keyreq }.map(&:last) } }
+    let(:block_parameter_extracter) { ->(method) { method.parameters.select { |type, kwarg| type == :block }.map(&:last) } }
+
+    describe '.find_preservation_document_by' do
+      subject { described_class.method(:find_preservation_document_by) }
+
+      it 'requires the :id  keyword (and does not require any others)' do
+        expect(required_parameters_extractor.call(subject)).to eq([:id])
+      end
+
+      it 'does not expect a block' do
+        expect(block_parameter_extracter.call(subject)).to be_empty
+      end
+    end
+    describe '.find_index_document_by' do
+      subject { described_class.method(:find_index_document_by) }
+
+      it 'requires the :id  keyword (and does not require any others)' do
+        expect(required_parameters_extractor.call(subject)).to eq([:id])
+      end
+
+      it 'does not expect a block' do
+        expect(block_parameter_extracter.call(subject)).to be_empty
+      end
+    end
+    describe '.each_preservation_document' do
+      subject { described_class.method(:each_preservation_document) }
+
+      it 'requires no keywords' do
+        expect(required_parameters_extractor.call(subject)).to eq([])
+      end
+
+      it 'expects a block' do
+        expect(block_parameter_extracter.call(subject)).to be_present
+      end
+    end
+    describe '.each_child_document_of' do
+      subject { described_class.method(:each_child_document_of) }
+
+      it 'requires the :document keyword (and does not require any others)' do
+        expect(required_parameters_extractor.call(subject)).to eq([:document])
+      end
+
+      it 'expects a block' do
+        expect(block_parameter_extracter.call(subject)).to be_present
+      end
+    end
+    describe '.write_document_attributes_to_index_layer' do
+    end
+  end
+end

data/lib/samvera/nesting_indexer/configuration.rb

@@ -0,0 +1,51 @@
+require 'samvera/nesting_indexer/adapters/abstract_adapter'
+require 'samvera/nesting_indexer/exceptions'
+
+module Samvera
+  # :nodoc:
+  module NestingIndexer
+    # @api public
+    # Responsible for the configuration of the Samvera::NestingIndexer
+    class Configuration
+      DEFAULT_MAXIMUM_NESTING_DEPTH = 15
+
+      def initialize(adapter: default_adapter, maximum_nesting_depth: DEFAULT_MAXIMUM_NESTING_DEPTH)
+        self.adapter = adapter
+        self.maximum_nesting_depth = maximum_nesting_depth
+      end
+
+      attr_reader :maximum_nesting_depth
+
+      def maximum_nesting_depth=(input)
+        @maximum_nesting_depth = input.to_i
+      end
+
+      # @api public
+      # @return Samvera::NestingIndexer::Adapters::AbstractAdapter
+      def adapter
+        @adapter || default_adapter
+      end
+
+      # @raise AdapterConfigurationError if the given adapter does not implement the correct interface
+      def adapter=(object)
+        object_methods = object.methods
+        adapter_methods = Adapters::AbstractAdapter.methods(false)
+        # Making sure that the adapter methods are all available in the object_methods
+        raise Exceptions::AdapterConfigurationError.new(object, adapter_methods) unless adapter_methods & object_methods == adapter_methods
+        @adapter = object
+      end
+
+      private
+
+      IN_MEMORY_ADAPTER_WARNING_MESSAGE =
+        "WARNING: You are using the default Samvera::NestingIndexer::Adapters::InMemoryAdapter for the Samvera::NestingIndexer.adapter.".freeze
+
+      def default_adapter
+        $stdout.puts IN_MEMORY_ADAPTER_WARNING_MESSAGE unless defined?(SUPPRESS_MEMORY_ADAPTER_WARNING)
+        require 'samvera/nesting_indexer/adapters/in_memory_adapter'
+        Adapters::InMemoryAdapter
+      end
+    end
+    private_constant :Configuration
+  end
+end

data/lib/samvera/nesting_indexer/documents.rb

@@ -0,0 +1,90 @@
+require 'dry-equalizer'
+
+module Samvera
+  module NestingIndexer
+    module Documents
+      # @api public
+      #
+      # A simplified document that reflects the necessary attributes for re-indexing
+      # the children of Fedora objects.
+      class PreservationDocument
+        def initialize(keywords = {})
+          @id = keywords.fetch(:id).to_s
+          @parent_ids = Array(keywords.fetch(:parent_ids))
+        end
+
+        # @api public
+        # @return String The Fedora object's PID
+        attr_reader :id
+
+        # @api public
+        #
+        # All of the direct parents of the Fedora document associated with the given PID.
+        #
+        # This does not include grandparents, great-grandparents, etc.
+        # @return Array<String>
+        attr_reader :parent_ids
+      end
+
+      # @api public
+      #
+      # A rudimentary representation of what is needed to reindex Solr documents
+      class IndexDocument
+        # A quick and dirty means of doing comparative logic
+        include Dry::Equalizer(:id, :sorted_parent_ids, :sorted_pathnames, :sorted_ancestors)
+
+        def initialize(keywords = {})
+          @id = keywords.fetch(:id).to_s
+          @parent_ids = Array(keywords.fetch(:parent_ids))
+          @pathnames = Array(keywords.fetch(:pathnames))
+          @ancestors = Array(keywords.fetch(:ancestors))
+        end
+
+        # @api public
+        # @return String The Fedora object's PID
+        attr_reader :id
+
+        # @api public
+        #
+        # All of the direct parents of the Fedora document associated with the given PID.
+        #
+        # This does not include grandparents, great-grandparents, etc.
+        # @return Array<String>
+        attr_reader :parent_ids
+
+        # @api public
+        #
+        # All nodes in the graph are addressable by one or more pathnames.
+        #
+        # If I have A, with parent B, and B has parents C and D, we have the
+        # following pathnames:
+        #   [D/B/A, C/B/A]
+        #
+        # In the graph representation, we can get to A by going from D to B to A, or by going from C to B to A.
+        # @return Array<String>
+        attr_reader :pathnames
+
+        # @api public
+        #
+        # All of the :pathnames of each of the documents ancestors. If I have A, with parent B, and B has
+        # parents C and D then we have the following ancestors:
+        #   [D/B], [C/B]
+        #
+        # @return Array<String>
+        attr_reader :ancestors
+
+        def sorted_parent_ids
+          parent_ids.sort
+        end
+
+        def sorted_pathnames
+          pathnames.sort
+        end
+
+        def sorted_ancestors
+          ancestors.sort
+        end
+      end
+    end
+  end
+end

data/lib/samvera/nesting_indexer/exceptions.rb

@@ -0,0 +1,35 @@
+module Samvera
+  module NestingIndexer
+    module Exceptions
+      class RuntimeError < ::RuntimeError
+      end
+
+      # Raised when we have a misconfigured adapter
+      class AdapterConfigurationError < RuntimeError
+        attr_reader :expected_methods
+        def initialize(object, expected_methods)
+          @expected_methods = expected_methods
+          super "Expected #{object.inspect} to implement #{expected_methods.inspect} methods"
+        end
+      end
+
+      # Raised when we may have detected a cycle within the graph
+      class CycleDetectionError < RuntimeError
+        attr_reader :id
+        def initialize(id)
+          @id = id
+          super "Possible graph cycle discovered related to PID=#{id}."
+        end
+      end
+      # A wrapper exception that includes the original exception and the id
+      class ReindexingError < RuntimeError
+        attr_reader :id, :original_exception
+        def initialize(id, original_exception)
+          @id = id
+          @original_exception = original_exception
+          super "Error PID=#{id} - #{original_exception}"
+        end
+      end
+    end
+  end
+end

data/lib/samvera/nesting_indexer/railtie.rb

@@ -0,0 +1,12 @@
+require 'rails/railtie'
+
+module Samvera
+  module NestingIndexer
+    # Connect into the boot sequence of a Rails application
+    class Railtie < Rails::Railtie
+      config.to_prepare do
+        Samvera::NestingIndexer.configure!
+      end
+    end
+  end
+end