WIP towards Alma SRU model

.env.test

@@ -1,9 +1,11 @@
 ALMA_OPENURL=https://na06.alma.exlibrisgroup.com/view/uresolver/01MIT_INST/openurl?
+EXL_INST_ID=01MIT_INST
 TURNSTILE_SITEKEY=test-sitekey
 TURNSTILE_SECRET=test-secret
 FEATURE_TIMDEX_FULLTEXT=true
 FEATURE_GEODATA=false
 FEATURE_PRIMO_NDE_LINKS=false
+MIT_ALMA_URL=https://mit.alma.exlibrisgroup.com
 MIT_PRIMO_URL=https://mit.primo.exlibrisgroup.com
 OPENALEX_EMAIL=FAKE_OPENALEX_EMAIL
 PRIMO_API_KEY=FAKE_PRIMO_API_KEY

.gitignore

@@ -11,6 +11,9 @@
 .env
 .env.development
 
+# qlty
+.qlty
+
 ## Environment normalization:
 /.bundle
 /vendor/bundle

app/models/alma_sru.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# Queries the Alma SRU endpoint for holdings data
+#
+# @reference https://developers.exlibrisgroup.com/alma/integrations/SRU/
+class AlmaSru
+  class LookupFailure < StandardError; end
+
+  class InvalidAlmaId < StandardError; end
+
+  NAMESPACE = { 'holding' => 'http://www.loc.gov/MARC21/slim' }.freeze
+
+  LOCATION_ORDER = {
+    'Hayden Library' => 0,
+    'Lewis Music Library' => 1,
+    'Rotch Library' => 2,
+    'Barker Library' => 3,
+    'Dewey Library' => 4
+  }.freeze
+
+  # lookup is the primary method of interacting with this model.
+  #
+  # It will receive an Alma ID, validate it, look it up in the Alma SRU, and return a formatted result.
+  #
+  # It accepts an "alma_client" argument for use when testing, but this is not used in normal operations.
+  def self.lookup(raw_identifier, alma_client: nil)
+    return [] unless alma_base_url
+
+    # Validate the raw identifier received. This will raise an InvalidAlmaId if validation fails.
+    identifier = validate_alma_id(raw_identifier)
+
+    # Build URL
+    url = alma_sru_url(identifier)
+
+    # Retrieve that URL
+    alma_http = setup(url, alma_client)
+
+    parse_response(alma_http.timeout(6).get(url), identifier)
+  rescue InvalidAlmaId
+    Rails.logger.debug("Invalid Alma ID: #{raw_identifier}")
+
+    []
+  rescue LookupFailure => e
+    Rails.logger.debug("Alma lookup failure: #{e}")
+
+    []
+  rescue HTTP::Error
+    Sentry.capture_message('Alma SRU connection failure')
+    Rails.logger.error('Alma SRU connection error')
+
+    []
+  end
+
+  # parse_response receives the raw response from the Alma SRU endpoint.
+  #
+  # For any non-200 response, it raises a LookupFailure.
+  #
+  # Other responses (in XML format) are parsed by Nokogiri, and we pluck content with an `AVA` tag.
+  def self.parse_response(raw_response, reference_identifier)
+    raise LookupFailure, raw_response.status unless raw_response.status == 200
+
+    parsed = Nokogiri::XML(raw_response.body.to_s)
+
+    # Confirm that control field 001 matches the identifier we received.
+    parsed_controlfield = fetch_controlfield(parsed)
+    raise LookupFailure, 'Control field mismatch' unless parsed_controlfield == reference_identifier
+
+    # Look up all AVA tags
+    parsed_availabilities = fetch_availabilities(parsed)
+
+    parsed_availabilities.map(&method(:format_availability))
+  end
+
+  # validate_alma_id ensures we are only submitting valid Alma IDs to the SRU endpoint.
+  #
+  # It needs to do two thigns:
+  # 1. Remove the "alma" prefix if one is present. Otherwise, no manipulation of the submitted value should occur.
+  # 2. Enforce the formatting requirements for a valid alma identifier (start with "99", and end with "6761").
+  def self.validate_alma_id(raw)
+    parsed = if raw.start_with?('alma')
+               raw.delete_prefix('alma')
+             else
+               raw
+             end
+
+    raise InvalidAlmaId unless parsed.to_s.start_with?('99')
+    raise InvalidAlmaId unless parsed.to_s.end_with?('6761')
+
+    parsed
+  end
+
+  # ava_to_hash takes an XML element that represents a single availability record
+  # and converts it to a hash. Each code is a key, while its text is the value.
+  def self.ava_to_hash(node)
+    rebuilt = {}
+
+    node.children.each do |child|
+      rebuilt[child.attribute_nodes[0].value] = child.text if child.instance_of?(Nokogiri::XML::Element)
+    end
+
+    rebuilt
+  end
+
+  # fetch_availabilities receives a parsed XML document (Nokogiri::XML::Document)
+  #
+  # This document is parsed using xpath to select on the nodes with an tag of AVA,
+  # and these are then sorted based on a preferred library order.
+  def self.fetch_availabilities(parsed_xml)
+    ava_list = parsed_xml.xpath("//holding:datafield[@tag='AVA']", NAMESPACE)
+
+    ava_list
+      .map { |el| ava_to_hash(el) }
+      .sort_by { |el| [LOCATION_ORDER.fetch(el['q'], 999), el['q'].to_s] }
+  end
+
+  # fetch_controlfield receives a parsed XML document (Nokogiri::XML::Document)
+  # and returns the controlfield with an 001 tag, if one exists.
+  def self.fetch_controlfield(parsed_xml)
+    parsed_xml.xpath("//holding:controlfield[@tag='001']", NAMESPACE)&.text
+  end
+
+  # format_availability receives a hash representing a single availability
+  # statement, and formats it for human readability.
+  def self.format_availability(availability)
+    "#{availability['e']&.humanize} at #{availability['q']} #{availability['c']} (#{availability['d']})"
+  end
+
+  def self.alma_base_url
+    ENV.fetch('MIT_ALMA_URL', nil)
+  end
+
+  def self.alma_sru_url(identifier)
+    # example identifier: 990000959610106761
+    "#{alma_base_url}/view/sru/#{ENV.fetch('EXL_INST_ID')}?version=1.2&operation=searchRetrieve&recordSchema=marcxml" \
+      "&query=alma.all_for_ui=#{identifier}"
+  end
+
+  def self.setup(url, alma_client)
+    alma_client || HTTP.persistent(url)
+  end
+end