samvera-nesting_indexer 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d85b5e9c924b8da1ab4155a9144073696f0d8aba
+  data.tar.gz: a49b5e3004e1b477d878343ce702a03ce02244e4
+SHA512:
+  metadata.gz: 2769007dd241f6eddf9be40857685f87f7e55a18ac103acb9674242df470388cb45dbc2cf7aa06a5b57bb20a278ea31c254eb3d1c06a225e5de0c79c514b60e5
+  data.tar.gz: bb3bbaface89adceb926133b867ccbe188ec026a1611e3db3c4180aacaddc91bc196a36805dc27c27a083c1776cc08b569107ea3412f4941497b59cf49bc2945

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,53 @@
+inherit_from: .rubocop_todo.yml
+
+################################################################################
+## Releasing the hounds in your local environment.
+##
+## Setup:
+## $ gem install rubocop
+##
+## Run:
+## $ rubocop ./path/to/file ./or/path/to/directory -c ./.hound.yml
+##
+## Generation Notes:
+##   This file was generated via the commitment:install generator. You are free
+##   and expected to change this file.
+################################################################################
+AllCops:
+  Include:
+    - Rakefile
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - 'bin/**/*'
+    - Gemfile
+    - Guardfile
+    - samvera-nesting_indexer.gemspec
+  TargetRubyVersion: 2.2
+LineLength:
+  Description: 'Limit lines to 160 characters.'
+  Max: 160
+  Enabled: true
+
+ModuleLength:
+  Exclude:
+    - 'spec/**/*'
+
+
+Style/StringLiterals:
+  Description: 'Checks if uses of quotes match the configured preference.'
+  Enabled: false
+
+PercentLiteralDelimiters:
+  Description: 'Use `%`-literal delimiters consistently'
+  Enabled: false
+
+Documentation:
+  Description: 'Document classes and non-namespace modules.'
+  Enabled: true
+  Exclude:
+  - spec/**/*
+  - test/**/*
+
+Style/WordArray:
+  Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,12 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2017-03-24 15:55:07 -0400 using RuboCop version 0.47.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 3
+# Configuration parameters: CountComments, ExcludedMethods.
+Metrics/BlockLength:
+  Max: 188

data/.ruby-version

@@ -0,0 +1 @@
+2.4.1

data/.travis.yml

@@ -0,0 +1,22 @@
+sudo: false
+cache: bundler
+
+language: ruby
+rvm:
+  - 2.3.1
+  - 2.2.5
+  - 2.2.2
+  - 2.1.10
+  - 2.0.0
+
+matrix:
+  allow_failures:
+    - rvm: "2.3.1"
+
+before_install: gem install bundler -v 1.12.5
+
+script: 'bundle exec rake'
+
+addons:
+    code_climate:
+        repo_token: 71b80cc45ed849e84e5943bb4874393b5ce26a2356381a839552395cd9b2f71a

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in samvera-indexer.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,49 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+notification :terminal_notifier, subtitle: 'Samvera::NestingIndexer', timeout: 4
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end
+
+guard :rubocop do
+  watch(%r{.+\.rb$})
+  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+end

data/LICENSE

@@ -0,0 +1,14 @@
+##########################################################################
+# Copyright 2014-2015 University of Notre Dame
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

data/README.md

@@ -0,0 +1,102 @@
+# Samvera::NestingIndexer
+
+[![Build Status](https://travis-ci.org/ndlib/samvera-indexer.png?branch=master)](https://travis-ci.org/ndlib/samvera-indexer)
+[![Test Coverage](https://codeclimate.com/github/ndlib/samvera-indexer/badges/coverage.svg)](https://codeclimate.com/github/ndlib/samvera-indexer)
+[![Code Climate](https://codeclimate.com/github/ndlib/samvera-indexer.png)](https://codeclimate.com/github/ndlib/samvera-indexer)
+[![Documentation Status](http://inch-ci.org/github/ndlib/samvera-indexer.svg?branch=master)](http://inch-ci.org/github/ndlib/samvera-indexer)
+[![APACHE 2 License](http://img.shields.io/badge/APACHE2-license-blue.svg)](./LICENSE)
+
+The Samvera::NestingIndexer gem is responsible for indexing the graph relationship of objects. It maps a PreservationDocument to an IndexDocument by mapping a PreservationDocument's direct parents into the paths to get from a root document to the given PreservationDocument.
+
+* [Background](#background)
+* [Concepts](#concepts)
+* [Examples](#examples)
+* [Adapters](#adapters)
+* [Considerations](#considerations)
+
+## Background
+
+This is a sandbox to work through the reindexing strategy as it relates to [CurateND Collections](https://github.com/ndlib/samvera_nd/issues/420). At this point the code is separate to allow for raid testing and prototyping (no sense spinning up SOLR and Fedora to walk an arbitrary graph).
+
+## Concepts
+
+As we are indexing objects, we have two types of documents:
+
+1. [PreservationDocument](./lib/samvera/nesting_indexer/documents.rb) - a light-weight representation of a Fedora object
+2. [IndexDocument](./lib/samvera/nesting_indexer/documents.rb) - a light-weight representation of a SOLR document object
+
+We have four attributes to consider for indexing the graph:
+
+1. id - the unique identifier for a document
+2. parent_ids - the ids for all of the parents of a given document
+3. pathnames - the paths to traverse from a root document to the given document
+4. ancestors - the pathnames of each of the ancestors
+
+See [Samvera::NestingIndexer::Documents::IndexDocument](./lib/samvera/nesting_indexer/documents.rb) for further discussion.
+
+To reindex a single document, we leverage the [`Samvera::NestingIndexer.reindex_relationships`](./lib/samvera/nesting_indexer.rb) method.
+
+## Examples
+
+Given the following PreservationDocuments:
+
+| PID | Parents |
+|-----|---------|
+| A   | -       |
+| B   | -       |
+| C   | A       |
+| D   | A, B    |
+| E   | C       |
+
+If we were to reindex the above PreservationDocuments, we will generate the following IndexDocuments:
+
+| PID | Parents | Pathnames  | Ancestors |
+|-----|---------|------------|-----------|
+| A   | -       | [A]        | []        |
+| B   | -       | [B]        | []        |
+| C   | A       | [A/C]      | [A]       |
+| D   | A, B    | [A/D, B/D] | [A, B]    |
+| E   | C       | [A/C/E]    | [A/C]     |
+
+For more scenarios, look at the [Reindex PID and Descendants specs](./spec/features/reindex_id_and_descendants_spec.rb).
+
+## Adapters
+
+An [AbstractAdapter](./lib/samvera/nesting_indexer/adapters/abstract_adapter.rb) provides the method interface for others to build against.
+
+The [InMemory adapter](./lib/samvera/nesting_indexer/adapters/in_memory_adapter.rb) is a reference implementation (and used to ease testing overhead).
+
+CurateND has implemented the [following adapter](https://github.com/ndlib/samvera_nd/blob/master/lib/samvera/library_collection_indexing_adapter.rb) for its LibraryCollection indexing.
+
+To define the adapter for your application:
+
+```ruby
+# In an application initializer (e.g. config/samvera_indexer_config.rb)
+Samvera::NestingIndexer.configure do |config|
+  config.adapter = MyCustomAdapter
+end
+```
+
+To best ensure you have implemented the adapter to spec:
+
+```ruby
+# In the spec for MyCustomAdapter
+require 'samvera/nesting_indexer/adapters/interface_behavior_spec'
+RSpec.describe MyCustomAdapter
+  it_behaves_like 'a Samvera::NestingIndexer::Adapter'
+end
+```
+
+
+
+
+[See CurateND for our adaptor configuration](https://github.com/ndlib/samvera_nd/blob/6fbe79c9725c0f8b4641981044ec250c5163053b/config/initializers/samvera_config.rb#L32-L35).
+
+## Considerations
+
+Given a single object A, when we reindex A, we:
+
+* Find the parent objects of A to calculate the ancestors and pathnames
+* Iterate through each descendant, in a breadth-first process, to reindex it (and each descendant's descendants).
+
+This is a potentially time consumptive process and should not be run within the request cycle.

data/Rakefile

@@ -0,0 +1,34 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+namespace :commitment do
+  require 'rubocop/rake_task'
+  # Why hound? Because hound-ci assumes this file, and perhaps you'll be using this
+  RuboCop::RakeTask.new
+
+  task :configure_test_for_code_coverage do
+    ENV['COVERAGE'] = 'true'
+  end
+  task :code_coverage do
+    require 'json'
+    $stdout.puts "Checking commitment:code_coverage"
+    coverage_percentage = JSON.parse(File.read('coverage/.last_run.json')).fetch('result').fetch('covered_percent').to_i
+    goal = 100
+    if goal > coverage_percentage
+      abort("Code Coverage Goal Not Met:\n\t#{coverage_percentage}%\tExpected\n\t#{goal}%\tActual")
+    end
+  end
+end
+
+task(
+  default: [
+    'commitment:rubocop',
+    'commitment:configure_test_for_code_coverage',
+    'spec',
+    'commitment:code_coverage'
+  ]
+)
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "samvera/nesting_indexer"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/samvera/nesting_indexer.rb

@@ -0,0 +1,82 @@
+require "samvera/nesting_indexer/version"
+require 'samvera/nesting_indexer/relationship_reindexer'
+require 'samvera/nesting_indexer/repository_reindexer'
+require 'samvera/nesting_indexer/configuration'
+require 'samvera/nesting_indexer/railtie' if defined?(Rails)
+
+module Samvera
+  # Responsible for indexing an object and its related child objects.
+  module NestingIndexer
+    # @api public
+    # Responsible for reindexing the associated document for the given :id and the descendants of that :id.
+    # In a perfect world we could reindex the id as well; But that is for another test.
+    #
+    # @param id [String] - The permanent identifier of the object that will be reindexed along with its children.
+    # @param maximum_nesting_depth [Integer] - there to guard against cyclical graphs
+    # @return [Boolean] - It was successful
+    # @raise Samvera::Exceptions::CycleDetectionError - A potential cycle was detected
+    def self.reindex_relationships(id:, maximum_nesting_depth: configuration.maximum_nesting_depth)
+      RelationshipReindexer.call(id: id, maximum_nesting_depth: maximum_nesting_depth, adapter: adapter)
+      true
+    end
+
+    class << self
+      # Here because I made a previous declaration that .reindex was part of the
+      # public API. Then I decided I didn't want to use that method.
+      alias reindex reindex_relationships
+    end
+
+    # @api public
+    # Responsible for reindexing the entire preservation layer.
+    # @param maximum_nesting_depth [Integer] - there to guard against cyclical graphs
+    # @return [Boolean] - It was successful
+    # @raise Samvera::Exceptions::CycleDetectionError - A potential cycle was detected
+    def self.reindex_all!(maximum_nesting_depth: configuration.maximum_nesting_depth)
+      # While the RepositoryReindexer is responsible for reindexing everything, I
+      # want to inject the lambda that will reindex a single item.
+      id_reindexer = method(:reindex_relationships)
+      RepositoryReindexer.call(maximum_nesting_depth: maximum_nesting_depth, id_reindexer: id_reindexer, adapter: adapter)
+      true
+    end
+
+    # @api public
+    #
+    # Contains the Samvera::NestingIndexer configuration information that is referenceable from wit
+    # @see Samvera::NestingIndexer::Configuration
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    # @api public
+    #
+    # Exposes the data adapter to use for the reindexing process.
+    #
+    # @see Samvera::NestingIndexer::Adapters::AbstractAdapter
+    # @return Object that implementes the Samvera::NestingIndexer::Adapters::AbstractAdapter method interface
+    def self.adapter
+      configuration.adapter
+    end
+
+    # @api public
+    #
+    # Capture the configuration information
+    #
+    # @see Samvera::NestingIndexer::Configuration
+    # @see .configuration
+    # @see Samvera::NestingIndexer::Railtie
+    def self.configure(&block)
+      @configuration_block = block
+      # The Rails load sequence means that some of the configured Targets may
+      # not be loaded; As such I am not calling configure! instead relying on
+      # Samvera::NestingIndexer::Railtie to handle the configure! call
+      configure! unless defined?(Rails)
+    end
+
+    # @api private
+    def self.configure!
+      return false unless @configuration_block.respond_to?(:call)
+      @configuration_block.call(configuration)
+      @configuration_block = nil
+    end
+  end
+end

data/lib/samvera/nesting_indexer/adapters.rb

@@ -0,0 +1,12 @@
+require 'samvera/nesting_indexer/adapters/abstract_adapter'
+require 'samvera/nesting_indexer/adapters/in_memory_adapter'
+
+module Samvera
+  module NestingIndexer
+    # A container for the various adapter implementations.
+    # @see Samvera::NestingIndexer::Adapters::AbstractAdapter
+    # @see Samvera::NestingIndexer::Adapters::InMemoryAdapter
+    module Adapters
+    end
+  end
+end