berkeley_library-alma 0.0.1

data/berkeley_library-alma.gemspec

@@ -0,0 +1,42 @@
+File.expand_path('lib', __dir__).tap do |lib|
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+end
+
+ruby_version = '>= 2.7'
+
+require 'berkeley_library/alma/module_info'
+
+Gem::Specification.new do |spec|
+  spec.name = BerkeleyLibrary::Alma::ModuleInfo::NAME
+  spec.author = BerkeleyLibrary::Alma::ModuleInfo::AUTHOR
+  spec.email = BerkeleyLibrary::Alma::ModuleInfo::AUTHOR_EMAIL
+  spec.summary = BerkeleyLibrary::Alma::ModuleInfo::SUMMARY
+  spec.description = BerkeleyLibrary::Alma::ModuleInfo::DESCRIPTION
+  spec.license = BerkeleyLibrary::Alma::ModuleInfo::LICENSE
+  spec.version = BerkeleyLibrary::Alma::ModuleInfo::VERSION
+  spec.homepage = BerkeleyLibrary::Alma::ModuleInfo::HOMEPAGE
+
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = ruby_version
+
+  spec.add_dependency 'berkeley_library-logging', '~> 0.2'
+  spec.add_dependency 'berkeley_library-marc', '~> 0.2.1'
+  spec.add_dependency 'berkeley_library-util', '~> 0.1', '>= 0.1.1'
+  spec.add_dependency 'nokogiri', '~> 1.12'
+
+  spec.add_development_dependency 'bundle-audit', '~> 0.1'
+  spec.add_development_dependency 'ci_reporter_rspec', '~> 1.0'
+  spec.add_development_dependency 'colorize', '~> 0.8'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.10'
+  spec.add_development_dependency 'rubocop', '= 1.11'
+  spec.add_development_dependency 'rubocop-rake', '= 0.6.0'
+  spec.add_development_dependency 'rubocop-rspec', '= 2.4.0'
+  spec.add_development_dependency 'simplecov', '~> 0.21'
+  spec.add_development_dependency 'simplecov-rcov', '~> 0.2'
+  spec.add_development_dependency 'webmock', '~> 3.12'
+  spec.add_development_dependency 'yard', '~> 0.9.27'
+end

data/bin/alma-mms-lookup

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+
+# ------------------------------------------------------------
+# Global setup
+
+# Don't buffer stdout or stderr
+$stdout.sync = true
+$stderr.sync = true
+
+# ------------------------------------------------------------
+# Dependencies
+
+# Require gems
+require 'bundler/setup'
+
+# Require lib directory
+unless $LOAD_PATH.include?((lib_path = File.expand_path('../lib', __dir__)))
+  puts "Adding #{lib_path} to $LOAD_PATH"
+  $LOAD_PATH.unshift(lib_path)
+end
+
+require 'berkeley_library/alma'
+
+# ------------------------------------------------------------
+# Configuration
+
+# Configure Alma URLs etc.
+BerkeleyLibrary::Alma.configure do
+  Config.default!
+end
+
+# Set log level
+BerkeleyLibrary::Logging.logger.level = Logger::Severity::WARN
+
+# ------------------------------------------------------------
+# Utility methods
+
+# Read raw IDs from  STDIN
+def raw_ids
+  @raw_ids ||= Enumerator.new do |y|
+    $stdin.each_line(chomp: true) do |ln|
+      y << ln.strip
+    end
+  end
+end
+
+# Read control field 001 from MARC record for specified record ID
+def id_001_for(record_id)
+  return unless record_id
+  return unless (marc_record = record_id.get_marc_record)
+  return unless (cf_001 = marc_record['001'])
+
+  cf_001.value
+end
+
+# ------------------------------------------------------------
+# Main program
+
+raw_ids.each do |raw_id|
+  record_id = BerkeleyLibrary::Alma::RecordId.parse(raw_id)
+  canonical_id = id_001_for(record_id)
+
+  puts [raw_id, record_id, canonical_id].join("\t")
+end

data/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  gem:
+    build:
+      context: .
+      target: development
+    ports:
+      - target: 3000
+        published: 3000
+    restart: always
+    volumes:
+      # Note that this mounts the *entire* repo directory (including
+      # files ignored in .dockerignore when building the image)
+      - ./:/opt/app
+
+version: "3.8"

data/lib/berkeley_library/alma/bib_number.rb

@@ -0,0 +1,90 @@
+require 'berkeley_library/alma/record_id'
+
+module BerkeleyLibrary
+  module Alma
+    # {RecordId} subclass representing a Millennium bib number.
+    class BibNumber
+      include RecordId
+
+      # ------------------------------------------------------------
+      # Accessors
+
+      # @return [String] the numeric part of the bib number, excluding check digit, as a string
+      attr_reader :digit_str
+
+      # @return [String] the check digit of the bib number, as a string
+      attr_reader :check_str
+
+      # ------------------------------------------------------------
+      # Initializer
+
+      # Initializes a new {BibNumber} from the specified string.
+      #
+      # @param [String] bib_number The bib number, with or without check digit
+      # @raise [ArgumentError] if the specified string is not an 8- or 9-digit bib number,
+      #        or if a 9-digit bib number has an incorrect check digit
+      def initialize(bib_number)
+        @digit_str, @check_str = split_bib(bib_number)
+      end
+
+      # ------------------------------------------------------------
+      # Instance methods
+
+      # Returns the full bib number, including the correct check digit, as a string.
+      #
+      # @return [String] the bib number, as a string
+      def full_bib
+        "b#{digit_str}#{check_str}"
+      end
+
+      # Returns the full bib number, including the correct check digit, as a string.
+      #
+      # @return [String] the bib number, as a string
+      def to_s
+        full_bib
+      end
+
+      # Returns the SRU query value for this MMS ID.
+      #
+      # Note that currently only UC Berkeley bib numbers (encoded `UCB-bXXXXXXXXX`)
+      # are supported.
+      #
+      # @return [String] the SRU query value
+      def sru_query_value
+        # TODO: stop hard-coding `UCB-`
+        other_system_number = "UCB-#{self}-#{Config.alma_institution_code.downcase}"
+        "alma.other_system_number=#{other_system_number}"
+      end
+
+      # ------------------------------------------------------------
+      # Private methods
+
+      private
+
+      def split_bib(bib_number)
+        raise ArgumentError, "Not a Millennium bib number: #{bib_number.inspect}" unless (md = MILLENNIUM_RECORD_RE.match(bib_number.to_s))
+
+        digit_str, check_str_orig = %i[digits check].map { |part| md[part] }
+        check_str = ensure_check_digit(digit_str, check_str_orig)
+
+        [digit_str, check_str]
+      end
+
+      def ensure_check_digit(digit_str, check_str_orig)
+        digits = digit_str.chars.map(&:to_i)
+        check_digit = calculate_check_digit(digits)
+        return check_digit if [nil, check_digit, 'a'].include?(check_str_orig)
+
+        raise ArgumentError, "#{digit_str}#{check_str_orig} check digit invalid: expected #{check_digit}, got #{check_str_orig}"
+      end
+
+      def calculate_check_digit(digits)
+        raise ArgumentError, "Not an 8-digit array : #{digits.inspect}" unless digits.is_a?(Array) && digits.size == 8
+
+        # From: http://liwong.blogspot.com/2018/04/recipe-computing-millennium-checkdigit.html
+        mod = digits.reverse.each_with_index.inject(0) { |sum, (v, i)| sum + (v * (i + 2)) } % 11
+        mod == 10 ? 'x' : mod.to_s
+      end
+    end
+  end
+end

data/lib/berkeley_library/alma/config.rb

@@ -0,0 +1,178 @@
+require 'berkeley_library/util/uris'
+
+module BerkeleyLibrary
+  module Alma
+    class Config
+      ALL_SETTINGS = %i[
+        alma_sru_host
+        alma_primo_host
+        alma_institution_code
+        alma_permalink_key
+      ].freeze
+
+      class << self
+        include BerkeleyLibrary::Util
+
+        # Alma SRU hostname, e.g. UC Berkeley = berkeley.alma.exlibrisgroup.com
+        def alma_sru_host
+          @alma_sru_host ||= value_from_rails_config(:alma_sru_host)
+        end
+
+        # Alma institution code, e.g. UC Berkeley = 01UCS_BER
+        def alma_institution_code
+          @alma_institution_code ||= value_from_rails_config(:alma_institution_code)
+        end
+
+        # Alma Primo host, e.g. UC Berkeley = search.library.berkeley.edu
+        def alma_primo_host
+          @alma_primo_host ||= value_from_rails_config(:alma_primo_host)
+        end
+
+        # View state key to use when generating Alma permalinks, e.g. `iqob43`; see
+        # [What is the key in short permalinks?](https://knowledge.exlibrisgroup.com/Primo/Knowledge_Articles/What_is_the_key_in_short_permalinks%3F)
+        # in the documentation
+        def alma_permalink_key
+          @alma_permalink_key ||= value_from_rails_config(:alma_permalink_key)
+        end
+
+        def alma_sru_base_uri
+          ensure_configured(:alma_sru_host, :alma_institution_code)
+
+          sru_base_uri_for(alma_sru_host, alma_institution_code)
+        end
+
+        def alma_permalink_base_uri
+          ensure_configured(:alma_primo_host, :alma_institution_code, :alma_permalink_key)
+
+          primo_permalink_base_uri_for(alma_primo_host, alma_institution_code, alma_permalink_key)
+        end
+
+        # Sets the Alma SRU hostname
+        #
+        # @param [String] hostname the hostname
+        # @return [String] the hostname
+        # @raise ArgumentError if the hostname is nil or empty
+        # @raise URI::InvalidURIError if the resulting SRU URI cannot be parsed
+        def alma_sru_host=(hostname)
+          raise ArgumentError, "Invalid hostname: #{hostname.inspect}" if hostname.nil? || hostname.empty?
+
+          sru_uri = sru_base_uri_for(hostname, '') # Catch bad URIs early
+          @alma_sru_host = sru_uri.host
+        end
+
+        # Sets the Alma Primo hostname
+        #
+        # @param [String] hostname the hostname
+        # @return [String] the hostname
+        # @raise ArgumentError if the hostname is nil or empty
+        # @raise URI::InvalidURIError if the resulting Primo permalink URI cannot be parsed
+        def alma_primo_host=(hostname)
+          raise ArgumentError, "Invalid hostname: #{hostname.inspect}" if hostname.nil? || hostname.empty?
+
+          primo_uri = primo_permalink_base_uri_for(hostname, 'XXX', 'abc123') # Catch bad URIs early
+          @alma_primo_host = primo_uri.host
+        end
+
+        # Sets the Alma SRU institution code
+        #
+        # @param [String] inst_code the institution code
+        # @return [String] the institution code
+        # @raise ArgumentError if the institution code is nil or empty
+        # @raise URI::InvalidURIError if the resulting SRU URI cannot be parsed
+        def alma_institution_code=(inst_code)
+          raise ArgumentError, "Invalid institution code: #{inst_code.inspect}" if inst_code.nil? || inst_code.empty?
+
+          sru_uri = sru_base_uri_for('example.org', inst_code) # Catch bad URIs early
+          @alma_institution_code = sru_uri.path.split('/').last
+        end
+
+        # Sets the Alma permalink key
+        #
+        # @param [String] permalink_key the permalink key
+        # @return [String] the permalink key
+        # @raise ArgumentError if the permalink key is nil or empty
+        # @raise URI::InvalidURIError if the resulting Primo permalink URI cannot be parsed
+        def alma_permalink_key=(permalink_key)
+          raise ArgumentError, "Invalid permalink key: #{permalink_key.inspect}" if permalink_key.nil? || permalink_key.empty?
+
+          sru_uri = primo_permalink_base_uri_for('example.org', 'XXX', permalink_key) # Catch bad URIs early
+          @alma_permalink_key = sru_uri.path.split('/').last
+        end
+
+        # Returns the list of missing settings.
+        # @return [Array<Symbol>] the missing settings.
+        def missing(*settings)
+          settings = ALL_SETTINGS if settings.empty?
+          [].tap do |unset|
+            settings.each do |setting|
+              unset << setting unless set?(setting)
+            end
+          end
+        end
+
+        def ensure_configured(*settings)
+          return if (missing_settings = missing(*settings)).empty?
+
+          raise ArgumentError, "Missing #{self} configuration settings: #{missing_settings.join(', ')}"
+        end
+
+        def default!
+          BerkeleyLibrary::Alma.configure do
+            config.alma_sru_host = ENV.fetch('LIT_ALMA_SRU_HOST', 'berkeley.alma.exlibrisgroup.com')
+            config.alma_institution_code = ENV.fetch('LIT_ALMA_INSTITUTION_CODE', '01UCS_BER')
+            config.alma_primo_host = ENV.fetch('LIT_ALMA_PRIMO_HOST', 'search.library.berkeley.edu')
+            config.alma_permalink_key = ENV.fetch('LIT_ALMA_PERMALINK_KEY', 'iqob43')
+          end
+        end
+
+        private
+
+        def sru_base_uri_for(domain, inst_code)
+          URIs.append("https://#{domain}/view/sru/", inst_code)
+        end
+
+        def primo_permalink_base_uri_for(alma_primo_host, inst_code, key)
+          URIs.append("https://#{alma_primo_host}/", 'permalink', inst_code, key)
+        end
+
+        # Gets the specified value from the Rails configuraiton
+        # @return [Object, nil] the value, or nil if there is no Rails configuration or the value is not set
+        def value_from_rails_config(sym)
+          return unless (config = rails_config)
+
+          config.send(sym)
+        end
+
+        def rails_config
+          return unless defined?(Rails)
+          return unless (application = Rails.application)
+
+          application.config
+        end
+
+        def set?(setting)
+          !Config.send(setting).nil?
+        end
+
+        def clear!
+          ALL_SETTINGS.each do |attr|
+            ivar_name = "@#{attr}"
+            next unless instance_variable_defined?(ivar_name)
+
+            send(:remove_instance_variable, ivar_name)
+          end
+        end
+      end
+    end
+
+    class << self
+      def config
+        BerkeleyLibrary::Alma::Config
+      end
+
+      def configure(&block)
+        class_eval(&block)
+      end
+    end
+  end
+end

data/lib/berkeley_library/alma/constants.rb

@@ -0,0 +1,16 @@
+require 'berkeley_library/alma/module_info'
+
+module BerkeleyLibrary
+  module Alma
+    module Constants
+      # 'x' represents a calculated check digit of 10; 'a' is a wildcard
+      MILLENNIUM_RECORD_RE = /^b(?<digits>[0-9]{8})(?<check>[0-9ax])?$/.freeze
+
+      # '99' is the Alma prefix for a Metadata Management System ID
+      # see https://knowledge.exlibrisgroup.com/Alma/Product_Documentation/010Alma_Online_Help_(English)/Metadata_Management/005Introduction_to_Metadata_Management/020Record_Numbers
+      ALMA_RECORD_RE = /^(?<type>99)(?<unique_part>[0-9]{9,12})(?<institution>[0-9]{4})$/.freeze
+
+      DEFAULT_USER_AGENT = "#{ModuleInfo::NAME} #{ModuleInfo::VERSION} (#{ModuleInfo::HOMEPAGE})".freeze
+    end
+  end
+end

data/lib/berkeley_library/alma/mms_id.rb

@@ -0,0 +1,100 @@
+require 'berkeley_library/util/uris'
+require 'berkeley_library/alma/record_id'
+
+module BerkeleyLibrary
+  module Alma
+    # {RecordId} subclass representing an Alma MMS ID. Note that only
+    # bibliographic records (prefix `99`) are supported.
+    #
+    # See [Record Numbers](https://knowledge.exlibrisgroup.com/Alma/Product_Documentation/010Alma_Online_Help_(English)/Metadata_Management/005Introduction_to_Metadata_Management/020Record_Numbers)
+    # in the Alma documentation.
+    class MMSID
+      include BerkeleyLibrary::Util
+      include RecordId
+
+      # ------------------------------------------------------------
+      # Constants
+
+      # The UC Berkeley prefix to the unique part of the MMS ID
+      UNIQ_PREFIX_UCB = '10'.freeze
+
+      # The four-digit institition code for UC berkeley
+      INST_CODE_UCB = '6532'.freeze
+
+      # ------------------------------------------------------------
+      # Accessors
+
+      # @return [String] the MMS ID, as a string
+      attr_reader :mms_id
+
+      # @return [String] the type prefix part of the MMS ID. Note that only bibliographic records
+      #         (prefix `99`) are supported.
+      attr_reader :type_prefix
+
+      # @return [String] the unique part of the record number
+      attr_reader :unique_part
+
+      # @return [String] the four-digit institution code
+      attr_reader :institution
+
+      # ------------------------------------------------------------
+      # Initializer
+
+      # Initializes a new {MMSID} from a string.
+      #
+      # @param id [String] the ID string
+      # @raise [ArgumentError] if the specified string is not an Alma bibliographic MMS ID.
+      def initialize(id)
+        @mms_id, @type_prefix, @unique_part, @institution = parse_mms_id(id)
+      end
+
+      # ------------------------------------------------------------
+      # Instance methods
+
+      # Returns the MMS ID as a string.
+      #
+      # @return [String] the MMS ID
+      def to_s
+        mms_id
+      end
+
+      # Returns the permalink URI for this MMS ID.
+      # Requires {Config#alma_permalink_base_uri} to be set.
+      #
+      # @return [URI] the permalink URI.
+      def permalink_uri
+        URIs.append(permalink_base_uri, "alma#{mms_id}")
+      end
+
+      # Returns the SRU query value for this MMS ID.
+      #
+      # @return [String] the SRU query value
+      def sru_query_value
+        "alma.mms_id=#{mms_id}"
+      end
+
+      # Whether this ID appears to be for a Berkeley record, based on its institution code and on
+      # whether the unique part of the ID starts with the expected prefix for Berkeley.
+      #
+      # @return [TrueClass, FalseClass] true if this ID appears to be for a Berkeley record, false otherwise
+      def berkeley?
+        unique_part.start_with?(UNIQ_PREFIX_UCB) && institution == INST_CODE_UCB
+      end
+
+      # ------------------------------------------------------------
+      # Private methods
+
+      private
+
+      def permalink_base_uri
+        Config.alma_permalink_base_uri
+      end
+
+      def parse_mms_id(id)
+        raise ArgumentError, "Not an MMS ID: #{id.inspect}" unless (md = ALMA_RECORD_RE.match(id.to_s))
+
+        md.to_a
+      end
+    end
+  end
+end

data/lib/berkeley_library/alma/module_info.rb

@@ -0,0 +1,14 @@
+module BerkeleyLibrary
+  module Alma
+    class ModuleInfo
+      NAME = 'berkeley_library-alma'.freeze
+      AUTHOR = 'David Moles'.freeze
+      AUTHOR_EMAIL = 'dmoles@berkeley.edu'.freeze
+      SUMMARY = 'Alma/Primo utilities for the UC Berkeley Library'.freeze
+      DESCRIPTION = 'A gem providing Alma/Primo-related utility code for the UC Berkeley Library'.freeze
+      LICENSE = 'MIT'.freeze
+      VERSION = '0.0.1'.freeze
+      HOMEPAGE = 'https://github.com/BerkeleyLibrary/alma'.freeze
+    end
+  end
+end

data/lib/berkeley_library/alma/record_id.rb

@@ -0,0 +1,113 @@
+require 'berkeley_library/logging'
+require 'berkeley_library/marc'
+require 'berkeley_library/util/uris'
+require 'berkeley_library/alma/constants'
+
+module BerkeleyLibrary
+  module Alma
+    # Encapsulates an ID that can be used to look up records in Alma via SRU.
+    module RecordId
+      include BerkeleyLibrary::Logging
+      include BerkeleyLibrary::Util
+      include Comparable
+      include Constants
+
+      # ------------------------------------------------------------
+      # Class methods
+
+      class << self
+        include Constants
+
+        # Parses a string record ID and returns a {RecordId} object. For convenience,
+        # also accepts a {RecordId} and simply returns it, so it can be used in
+        # situations where it may not be clear whether the ID has already been parsed.
+        #
+        # @param id [String, RecordId] the ID to parse
+        # @return [RecordId, nil] an {MMSID} or {BibNumber}, depending on the type of ID,
+        #         or `nil` if the specified `id` is neither an MMS ID nor a bib number
+        # @raise [ArgumentError] if the specified string is a correctly formatted Millennium
+        #        bib number, but has an incorrect check digit
+        def parse(id)
+          # noinspection RubyMismatchedReturnType
+          return id if id.is_a?(RecordId)
+
+          return MMSID.new(id) if ALMA_RECORD_RE =~ id
+          return BibNumber.new(id) if MILLENNIUM_RECORD_RE =~ id
+        end
+      end
+
+      # ------------------------------------------------------------
+      # Instance methods
+
+      # Returns a URI for retrieving MARCXML from this record via SRU.
+      # Requires {Config#alma_sru_base_uri} to be set.
+      #
+      # @return [URI] the MARC URI
+      def marc_uri
+        query_string = URI.encode_www_form(
+          'version' => '1.2',
+          'operation' => 'searchRetrieve',
+          'query' => sru_query_value
+        )
+
+        URIs.append(Config.alma_sru_base_uri, '?', query_string)
+      end
+
+      # Makes an SRU query for this record and returns a MARC record, or nil if the
+      # record is not found.
+      #
+      # Note that in the event the SRU query finds multiple records, only the first
+      # record is returned.
+      #
+      # @return [MARC::Record, nil] the MARC record
+      # rubocop:disable Naming/AccessorMethodName
+      def get_marc_record
+        marc_xml = get_marc_xml
+        logger.warn("GET #{marc_uri} did not return a MARC record") unless (marc_record = parse_marc_xml(marc_xml))
+        marc_record
+      end
+      # rubocop:enable Naming/AccessorMethodName
+
+      # Makes an SRU query for this record and returns the XML query response
+      # as a string.
+      #
+      # @return [String, nil] the SRU query response body, or nil in the event of an error.
+      # rubocop:disable Naming/AccessorMethodName
+      def get_marc_xml
+        URIs.get(marc_uri, headers: { user_agent: DEFAULT_USER_AGENT })
+      rescue RestClient::Exception => e
+        logger.warn("GET #{marc_uri} failed", e)
+        nil
+      end
+      # rubocop:enable Naming/AccessorMethodName
+
+      # ------------------------------------------------------------
+      # Comparable
+
+      # Compares this {RecordId} with another based on their string representations.
+      #
+      # @see Comparable#<=>
+      # @return [Integer, nil]
+      def <=>(other)
+        return 0 if equal?(other)
+        return unless other
+        return unless other.is_a?(RecordId)
+
+        to_s <=> other.to_s
+      end
+
+      # ------------------------------------------------------------
+      # Private methods
+
+      private
+
+      def parse_marc_xml(xml)
+        return unless xml
+
+        input = StringIO.new(xml.scrub)
+        reader = MARC::XMLReader.new(input)
+        reader.first
+      end
+    end
+  end
+end

data/lib/berkeley_library/alma.rb

@@ -0,0 +1 @@
+Dir.glob(File.expand_path('alma/*.rb', __dir__)).sort.each(&method(:require))

data/rakelib/bundle.rake

@@ -0,0 +1,8 @@
+namespace :bundle do
+  desc 'Updates the ruby-advisory-db then runs bundle-audit'
+  task :audit do
+    require 'bundler/audit/cli'
+    Bundler::Audit::CLI.start ['update']
+    Bundler::Audit::CLI.start %w[check --ignore CVE-2015-9284]
+  end
+end

data/rakelib/coverage.rake

@@ -0,0 +1,11 @@
+require 'ci/reporter/rake/rspec'
+
+# Configure CI::Reporter report generation
+ENV['GENERATE_REPORTS'] ||= 'true'
+ENV['CI_REPORTS'] = 'artifacts/rspec'
+
+desc 'Run all specs in spec directory, with coverage'
+task coverage: ['ci:setup:rspec'] do
+  ENV['COVERAGE'] ||= 'true'
+  Rake::Task[:spec].invoke
+end