noid-rails 3.0.0

data/db/migrate/20161021203429_rename_minter_state_random_to_rand.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RenameMinterStateRandomToRand < ActiveRecord::Migration[4.2]
+  def change
+    rename_column :minter_states, :random, :rand
+  end
+end

data/lib/generators/noid/rails/install_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Noid
+  module Rails
+    # Generates the migrations into the host application
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root ::File.expand_path('../templates', __FILE__)
+
+      desc <<~DESCRIPTION
+        Copies DB migrations
+      DESCRIPTION
+
+      def banner
+        say_status('info', 'Installing noid-rails', :blue)
+      end
+
+      def migrations
+        rake 'noid_rails_engine:install:migrations'
+      end
+    end
+  end
+end

data/lib/generators/noid/rails/seed_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Noid
+  module Rails
+    # Initializes the database with a noid namespace
+    class SeedGenerator < ::Rails::Generators::Base
+      source_root ::File.expand_path('../templates', __FILE__)
+      argument :namespace, type: :string, default: Noid::Rails.config.namespace
+      argument :template, type: :string, default: Noid::Rails.config.template
+
+      desc <<~DESCRIPTION
+        Seeds DB from Noid::Rails.config (or command-line overrides)
+      DESCRIPTION
+
+      def banner
+        say_status('info', "Initializing database table for namespace:template of '#{namespace}:#{template}'", :blue)
+      end
+
+      def checks
+        if namespace != Noid::Rails.config.namespace
+          say_status('warn', 'Be sure to use an initializer to do ' \
+                             "'Noid::Rails.config.namespace = #{namespace}'", :red)
+        end
+        return if template == Noid::Rails.config.template
+        say_status('warn', 'Be sure to use an initializer to do ' \
+                           "Noid::Rails.config.template = #{template}'", :red)
+      end
+
+      def seed_row
+        MinterState.seed!(
+          namespace: namespace,
+          template: template
+        )
+      end
+    end
+  end
+end

data/lib/noid/rails/config.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Noid
+  module Rails
+    # Configuration parameters for creating identifiers
+    class Config
+      attr_writer :template, :statefile, :namespace, :minter_class, :identifier_in_use
+
+      def template
+        @template ||= '.reeddeeddk'
+      end
+
+      def statefile
+        @statefile ||= '/tmp/minter-state'
+      end
+
+      def namespace
+        @namespace ||= 'default'
+      end
+
+      def minter_class
+        @minter_class ||= Minter::File
+      end
+
+      # A check to guarantee the identifier is not already in use. When true,
+      # the minter will continue to cycle through ids until it finds one that
+      # returns false
+      def identifier_in_use
+        @identifier_in_use = lambda do |_id|
+          false
+        end
+      end
+    end
+  end
+end

data/lib/noid/rails/engine.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'rails'
+
+module Noid
+  module Rails
+    class Engine < ::Rails::Engine
+    end
+  end
+end

data/lib/noid/rails/minter/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'noid'
+
+module Noid
+  module Rails
+    module Minter
+      # @abstract the base class for minters
+      class Base < ::Noid::Minter
+        ##
+        # @param template [#to_s] a NOID template
+        # @see Noid::Template
+        def initialize(template = default_template)
+          super(template: template.to_s)
+        end
+
+        ##
+        # Sychronously mint a new identifier.
+        #
+        # @return [String] the minted identifier
+        def mint
+          Mutex.new.synchronize do
+            loop do
+              pid = next_id
+              return pid unless identifier_in_use?(pid)
+            end
+          end
+        end
+
+        ##
+        # @return [Hash{Symbol => String, Object}] representation of the current minter state
+        def read
+          raise NotImplementedError, 'Implement #read in child class'
+        end
+
+        ##
+        # Updates the minter state to that of the `minter` parameter.
+        #
+        # @param minter [Minter::Base]
+        # @return [void]
+        def write!(_)
+          raise NotImplementedError, 'Implement #write! in child class'
+        end
+
+        private
+
+        def identifier_in_use?(id)
+          Noid::Rails.config.identifier_in_use.call(id)
+        end
+
+        ##
+        # @return [#to_s] the default template for this
+        def default_template
+          Noid::Rails.config.template
+        end
+
+        ##
+        # @return [String] a new identifier
+        def next_id
+          raise NotImplementedError, 'Implement #next_id in child class'
+        end
+      end
+    end
+  end
+end

data/lib/noid/rails/minter/db.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'noid'
+
+module Noid
+  module Rails
+    module Minter
+      # A minter backed by a database table. You would select this if you
+      # need to mint identifers on several distributed front-ends that do not
+      # share a common file system.
+      class Db < Base
+        def read
+          deserialize(instance)
+        end
+
+        def write!(minter)
+          serialize(instance, minter)
+        end
+
+        protected
+
+        # @param [MinterState] inst minter state to be converted
+        # @return [Hash{Symbol => String, Object}] minter state as a Hash, like #read
+        # @see #read, Noid::Rails::Minter::Base#read
+        def deserialize(inst)
+          filtered_hash = inst.as_json.slice('template', 'counters', 'seq', 'rand', 'namespace')
+          if filtered_hash['counters']
+            filtered_hash['counters'] = JSON.parse(filtered_hash['counters'],
+                                                   symbolize_names: true)
+          end
+          filtered_hash.symbolize_keys
+        end
+
+        # @param [MinterState] inst a locked row/object to be updated
+        # @param [::Noid::Minter] minter state containing the updates
+        def serialize(inst, minter)
+          # namespace and template are the same, now update the other attributes
+          inst.update_attributes!(
+            seq: minter.seq,
+            counters: JSON.generate(minter.counters),
+            rand: Marshal.dump(minter.instance_variable_get(:@rand))
+          )
+        end
+
+        # Uses pessimistic lock to ensure the record fetched is the same one updated.
+        # Should be fast enough to avoid terrible deadlock.
+        # Must lock because of multi-connection context! (transaction is per connection -- not enough)
+        # The DB table will only ever have at most one row per namespace.
+        # The 'default' namespace row is inserted by `rails generate noid:rails:seed`
+        # or autofilled by instance below.
+        # If you want another namespace, edit your config initialzer to something like:
+        #     Noid::Rails.config.namespace = 'druid'
+        #     Noid::Rails.config.template = '.reeedek'
+        # and in your app run:
+        #     bundle exec rails generate noid:rails:seed
+        def next_id
+          id = nil
+          MinterState.transaction do
+            locked = instance
+            minter = ::Noid::Minter.new(deserialize(locked))
+            id = minter.mint
+            serialize(locked, minter)
+          end
+          id
+        end
+
+        # @return [MinterState]
+        def instance
+          MinterState.lock.find_by!(
+            namespace: Noid::Rails.config.namespace,
+            template: Noid::Rails.config.template
+          )
+        rescue ActiveRecord::RecordNotFound
+          MinterState.seed!(
+            namespace: Noid::Rails.config.namespace,
+            template: Noid::Rails.config.template
+          )
+        end
+      end
+    end
+  end
+end

data/lib/noid/rails/minter/file.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'noid'
+
+module Noid
+  module Rails
+    module Minter
+      # A file based minter. This is a simple case.
+      class File < Base
+        attr_reader :statefile
+
+        def initialize(template = default_template, statefile = default_statefile)
+          @statefile = statefile
+          super(template)
+        end
+
+        def default_statefile
+          Noid::Rails.config.statefile
+        end
+
+        def read
+          with_file do |f|
+            state_for(f)
+          end
+        end
+
+        def write!(minter)
+          with_file do |f|
+            # Wipe prior contents so the new state can be written from the beginning of the file
+            f.truncate(0)
+            f.write(Marshal.dump(minter.dump))
+          end
+        end
+
+        protected
+
+        def with_file
+          ::File.open(statefile, 'a+b', 0o644) do |f|
+            f.flock(::File::LOCK_EX)
+            # Files opened in append mode seek to end of file
+            f.rewind
+            yield f
+          end
+        end
+
+        # rubocop:disable Security/MarshalLoad
+        def state_for(io_object)
+          Marshal.load(io_object.read)
+        rescue TypeError, ArgumentError
+          { template: template }
+        end
+        # rubocop:enable Security/MarshalLoad
+
+        def next_id
+          state = read
+          state[:template] &&= state[:template].to_s
+          minter = ::Noid::Minter.new(state) # minter w/in the minter, lives only for an instant
+          id = minter.mint
+          write!(minter)
+          id
+        end
+      end
+    end
+  end
+end

data/lib/noid/rails/minter.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'minter/base'
+require_relative 'minter/file'
+require_relative 'minter/db'

data/lib/noid/rails/rspec.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Noid
+  module Rails
+    ##
+    # Provides a test minter conforming to the `Noid::Rails::Minter`
+    # interface for use in unit tests. The test minter is faster and avoids
+    # unexpected interactions with cleanup code commonly runs in test suites
+    # (e.g. database cleanup).
+    #
+    # Applications should reenable their production minter for integration tests
+    # when appropriate
+    #
+    # @example general use
+    #   Noid::Rails::RSpec.disable_production_minter!
+    #   # some unit tests with the test minter
+    #   Noid::Rails::RSpec.enable_production_minter!
+    #   # some integration tests with the original minter
+    #
+    # @example using a custom test minter
+    #   Noid::Rails::RSpec.disable_production_minter!(test_minter: Minter)
+    #
+    # @example use when included in RSpec config
+    #   require 'noid/rails/rspec'
+    #
+    #   RSpec.configure do |config|
+    #     config.include(Noid::Rails::RSpec)
+    #   end
+    #
+    #   before(:suite) { disable_production_minter! }
+    #   after(:suite)  { enable_production_minter! }
+    #
+    module RSpec
+      DEFAULT_TEST_MINTER = Noid::Rails::Minter::File
+
+      ##
+      # Replaces the configured production minter with a test minter.
+      #
+      # @param test_minter [Class] a Noid::Rails::Minter implementation
+      #   to use as a replacement minter
+      # @return [void]
+      def disable_production_minter!(test_minter: DEFAULT_TEST_MINTER)
+        return nil if @original_minter
+
+        @original_minter = Noid::Rails.config.minter_class
+
+        Noid::Rails.configure do |noid_config|
+          noid_config.minter_class = test_minter
+        end
+      end
+
+      ##
+      # Re-enables the original configured minter.
+      #
+      # @return [void]
+      def enable_production_minter!
+        return nil unless @original_minter
+
+        Noid::Rails.configure do |noid_config|
+          noid_config.minter_class = @original_minter
+        end
+
+        @original_minter = nil
+      end
+    end
+  end
+end

data/lib/noid/rails/service.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'noid'
+
+module Noid
+  module Rails
+    # A service that validates and mints identifiers
+    class Service
+      attr_reader :minter
+
+      def initialize(minter = default_minter)
+        @minter = minter
+      end
+
+      delegate :valid?, to: :minter
+
+      delegate :mint, to: :minter
+
+      protected
+
+      def default_minter
+        Noid::Rails.config.minter_class.new
+      end
+    end
+  end
+end

data/lib/noid/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Noid
+  module Rails
+    VERSION = '3.0.0'
+  end
+end

data/lib/noid-rails.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'noid/rails/version'
+require 'noid/rails/config'
+require 'noid/rails/engine'
+require 'noid/rails/service'
+require 'noid/rails/minter'
+
+module Noid
+  # A package to integrate Noid identifers with Rails projects
+  module Rails
+    class << self
+      def configure
+        yield config
+      end
+
+      def config
+        @config ||= Config.new
+      end
+
+      def treeify(identifier)
+        raise ArgumentError, 'Identifier must be a string of size > 0 in order to be treeified' if identifier.blank?
+        head = identifier.split('/').first
+        head.gsub!(/#.*/, '')
+        (head.scan(/..?/).first(4) + [identifier]).join('/')
+      end
+    end
+  end
+end

data/lib/tasks/noid_tasks.rake

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'noid-rails'
+require 'noid'
+require 'yaml'
+
+namespace :noid do
+  namespace :rails do
+    namespace :migrate do
+      desc 'Migrate minter state file from YAML to Marshal'
+      task :yaml_to_marshal do
+        statefile = ENV.fetch('RAILS_NOID_STATEFILE', Noid::Rails.config.statefile)
+        raise "File not found: #{statefile}\nAborting" unless File.exist?(statefile)
+        puts "Migrating #{statefile} from YAML to Marshal serialization..."
+        File.open(statefile, 'a+b', 0o644) do |f|
+          f.flock(File::LOCK_EX)
+          f.rewind
+          begin
+            yaml_state = YAML.safe_load(f)
+          rescue Psych::SyntaxError
+            raise "File not valid YAML: #{statefile}\nAborting."
+          end
+          minter = Noid::Minter.new(yaml_state)
+          f.truncate(0)
+          new_state = Marshal.dump(minter.dump)
+          f.write(new_state)
+        end
+        puts 'Done!'
+      end
+
+      desc 'Migrate minter state from file to database'
+      task file_to_database: :environment do
+        statefile = ENV.fetch('RAILS_NOID_STATEFILE', Noid::Rails.config.statefile)
+        raise "File not found: #{statefile}\nAborting" unless File.exist?(statefile)
+        puts "Migrating #{statefile} to database..."
+        state = Noid::Rails::Minter::File.new.read
+        minter = Noid::Minter.new(state)
+        new_state = Noid::Rails::Minter::Db.new
+        new_state.write!(minter)
+        puts 'Done!'
+      end
+
+      desc 'Migrate minter state from database to file'
+      task database_to_file: :environment do
+        statefile = ENV.fetch('RAILS_NOID_STATEFILE', Noid::Rails.config.statefile)
+        if File.exist?(statefile)
+          raise "File already exists (delete it first if it's not valuable): " \
+                "#{statefile}\nAborting"
+        end
+        puts "Migrating minter state from database to #{statefile}..."
+        state = Noid::Rails::Minter::Db.new.read
+        minter = Noid::Minter.new(state)
+        new_state = Noid::Rails::Minter::File.new
+        new_state.write!(minter)
+        puts 'Done!'
+      end
+    end
+  end
+end

data/noid-rails.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'noid/rails/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'noid-rails'
+  spec.version       = Noid::Rails::VERSION
+  spec.authors       = ['Michael J. Giarlo']
+  spec.email         = ['leftwing@alumni.rutgers.edu']
+  spec.summary       = 'Noid identifier services for Rails-based applications'
+  spec.description   = 'Noid identifier services for Rails-based applications.'
+  spec.homepage      = 'https://github.com/samvera/noid-rails'
+  spec.license       = 'Apache2'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^spec/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'actionpack', '>= 5.0.0', '< 6'
+  spec.add_dependency 'noid', '~> 0.9'
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'engine_cart', '~> 1.0'
+  spec.add_development_dependency 'rake', '>= 11'
+  spec.add_development_dependency 'rspec', '~> 3.2'
+  spec.add_development_dependency 'rubocop', '~> 0.52.0'
+  spec.add_development_dependency 'rubocop-rspec', '~> 1.20.1'
+  spec.add_development_dependency 'sqlite3'
+end

data/spec/models/minter_state_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+RSpec.describe MinterState, type: :model do
+  include MinterStateHelper
+  before { reset_minter_state_table }
+  after { reset_minter_state_table }
+
+  let(:state) { described_class.new }
+  let(:first) { described_class.first }
+
+  it 'db is seeded with first row' do
+    expect { first }.not_to raise_error
+    expect(first.namespace).to eq 'default'
+    expect(first.template).to eq '.reeddeeddk'
+    expect(first.seq).to eq 0
+    expect(described_class.group(:namespace).count).to eq('default' => 1)
+  end
+  describe 'validation' do
+    it 'blocks invalid template' do
+      expect { state.save! }.to raise_error(ActiveRecord::RecordInvalid) # empty
+      state.template = 'bad_template'
+      expect { state.save! }.to raise_error(ActiveRecord::RecordInvalid)
+      state.template = 'reeddddk' # close, but missing '.'
+      expect { state.save! }.to raise_error(ActiveRecord::RecordInvalid)
+    end
+    it 'allows valid template (edit)' do
+      first.template = '.reeddddk'
+      expect { first.save! }.not_to raise_error # OK!
+    end
+    it 'blocks new record in same namespace' do
+      state.template = '.reeddddk'
+      expect { state.save! }.to raise_error(ActiveRecord::RecordInvalid)
+    end
+    it 'allows new record in distinct namespace' do
+      state.template = '.reeddddk'
+      state.namespace = 'foobar'
+      expect { state.save! }.not_to raise_error # OK!
+      expect(described_class.group(:namespace).count).to eq('default' => 1, 'foobar' => 1)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+ENV['RAILS_ENV'] ||= 'test'
+
+def coverage_needed?
+  ENV['COVERAGE'] || ENV['TRAVIS']
+end
+
+if coverage_needed?
+  require 'simplecov'
+  require 'coveralls'
+  SimpleCov.root(File.expand_path('../..', __FILE__))
+  SimpleCov.formatter = Coveralls::SimpleCov::Formatter
+  SimpleCov.start('rails') do
+    add_filter '/.internal_test_app'
+    add_filter '/lib/generators'
+    add_filter '/spec'
+    add_filter '/lib/noid/rails/version.rb'
+  end
+  SimpleCov.command_name 'spec'
+end
+
+require 'engine_cart'
+EngineCart.load_application!
+
+require 'noid-rails'
+require 'byebug' unless ENV['CI']
+
+Dir[File.dirname(__FILE__) + '/support/**/*.rb'].each { |f| require f }
+
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+  config.filter_run_when_matching :focus
+end

data/spec/support/minterstate_table.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MinterStateHelper
+  # Simple truncation is not enough, since we also need seed data
+  def reset_minter_state_table
+    MinterState.destroy_all
+    MinterState.create!(
+      namespace: 'default',
+      template: '.reeddeeddk',
+      seq: 0
+    )
+  end
+end