Create integration with Libkey

.env.test

@@ -13,3 +13,5 @@ TACOS_SOURCE=FAKE_TACOS_SOURCE
 TIMDEX_GRAPHQL=https://FAKE_TIMDEX_HOST/graphql
 TIMDEX_HOST=FAKE_TIMDEX_HOST
 TIMDEX_INDEX=FAKE_TIMDEX_INDEX
+LIBKEY_ID=FAKE_LIBKEY_ID
+LIBKEY_KEY=FAKE_LIBKEY_KEY

README.md

@@ -112,6 +112,8 @@ may have unexpected consequences if applied to other TIMDEX UI apps.
 - `FILTER_SUBJECT`: The name to use instead of "Subject" for that filter / aggregation.
 - `GLOBAL_ALERT`: The main functionality for this comes from our theme gem, but when set the value will be rendered as
   safe html above the main header of the site.
+- `LIBKEY_KEY`: An access key assigned by Third Iron to enable this application to interact with the Libkey service.
+- `LIBKEY_ID`: An institutional ID value assigned by Third Iron to interact with the Libkey service.
 - `MATOMO_CONTAINER_URL`: This is one of two options for integrating a TIMDEX UI application with Matomo - the Tag Manager. This is the only parameter needed for using a tag manager container.
 - `MATOMO_SITE_ID`: Integrating with Matomo using the legacy approach (instead of Tag Manager) requires two values: the site id and a URL. This is one of those legacy values.
 - `MATOMO_URL`: Integrating with Matomo using the legacy approach (instead of Tag Manager) requires two values: the site id and a URL. This is one of those legacy values.
@@ -146,6 +148,8 @@ that matches `TACOS_URL`. Ex: If `TACOS_URL` is `http://localhost:3001/graphql`
 
 When generating new cassettes for timdex-ui, update `.env.test` to have appropriate values for your test for `TIMDEX_GRAPHQL` and `TIMDEX_HOST`. This will allow the cassettes to be generated from any TIMDEX source with the data you need, but be sure to set them back to the original values after the cassette are generated. When the values are not set to the "fake" values we normally store, many tests will fail due to how the cassettes re-write values to normalize what we store.
 
+If you need to regenerate any cassettes for interactions with Libkey, you will need to temporarily assign real values for the `LIBKEY_ID` and `LIBKEY_KEY` variables. These should also be reset back to the fake values after regenerating cassettes.
+
 `.env.test` should be commited to the repository, but should not include real values for a TIMDEX source even though they are not secrets. We want to use fake values to allow us to normalize our cassettes without forcing us to always generate them from a single TIMDEX source.
 
 ### Updating GraphQL Schema

app/controllers/libkey_controller.rb

@@ -0,0 +1,15 @@
+class LibkeyController < ApplicationController
+  layout false
+
+  def lookup
+    return unless Libkey.enabled? && expected_params?
+
+    @libkey = Libkey.lookup(type: params[:type], identifier: params[:identifier])
+  end
+
+  private
+
+  def expected_params?
+    params[:type].present? && params[:identifier].present?
+  end
+end

app/models/libkey.rb

@@ -0,0 +1,68 @@
+# TODO: Need some documentation block to explain what we use Libkey for...
+class Libkey
+  class LookupFailure < StandardError; end
+
+  BASEURL = 'https://public-api.thirdiron.com/public/v1/libraries'.freeze
+
+  # enabled? confirms that all required environment variables are set.
+  #
+  # @return Boolean
+  def self.enabled?
+    libkey_id.present? && libkey_key.present?
+  end
+
+  def self.lookup(type:, identifier:, libkey_client: nil)
+    return unless enabled?
+    return unless %w[doi pmid].include?(type)
+
+    url = libkey_url(type, identifier)
+
+    libkey_http = setup(url, libkey_client)
+
+    begin
+      raw_response = libkey_http.timeout(6).get(url)
+      raise LookupFailure, raw_response.status unless raw_response.status == 200
+
+      json_response = JSON.parse(raw_response.to_s)
+      extract_metadata(json_response)
+    rescue LookupFailure => e
+      Sentry.set_tags('mitlib.libkeyurl': url)
+      Sentry.set_tags('mitlib.libkeystatus': e.message)
+      Sentry.capture_message('Unexpected Libkey response status')
+      nil
+    rescue HTTP::Error
+      Rails.logger.error('Libkey connection error')
+      { 'error' => 'A connection error has occurred' }
+    rescue JSON::ParserError
+      Rails.logger.error('Libkey parsing error')
+      { 'error' => 'A parsing error has occurred' }
+    end
+  end
+
+  def self.extract_metadata(external_data)
+    return unless external_data['data']['bestIntegratorLink']
+
+    {
+      link: external_data['data']['bestIntegratorLink']['bestLink'],
+      text: external_data['data']['bestIntegratorLink']['recommendedLinkText'],
+      type: external_data['data']['bestIntegratorLink']['linkType'] # Not sure whether this belongs here.
+    }
+  end
+
+  def self.libkey_id
+    ENV.fetch('LIBKEY_ID', nil)
+  end
+
+  def self.libkey_key
+    ENV.fetch('LIBKEY_KEY', nil)
+  end
+
+  def self.libkey_url(type, identifier)
+    "#{BASEURL}/#{libkey_id}/articles/#{type}/#{identifier}?access_token=#{libkey_key}"
+  end
+
+  def self.setup(url, libkey_client)
+    libkey_client || HTTP.persistent(url)
+                         .headers(accept: 'application/json')
+  end
+end

app/views/libkey/lookup.html.erb

@@ -0,0 +1,3 @@
+<% if Libkey.enabled? && @libkey.present? %>
+  <%= link_to( @libkey[:text], @libkey[:link], class: 'button button-primary' ) %>
+<% end %>

config/routes.rb

@@ -3,6 +3,8 @@
 
   get 'analyze', to: 'tacos#analyze'
 
+  get 'lookup', to: 'libkey#lookup'
+
   get 'record/(:id)',
       to: 'record#view',
       as: 'record',

test/controllers/libkey_controller_test.rb

@@ -0,0 +1,67 @@
+require 'test_helper'
+
+class LibkeyControllerTest < ActionDispatch::IntegrationTest
+  test 'lookup route exists with no content' do
+    # No cassette because this never results in traffic to Libkey
+    get '/lookup'
+
+    assert_response :success
+    assert_equal response.body, ''
+  end
+
+  test 'lookup route returns nothing without required parameters' do
+    # No cassettes because these never result in traffic to Libkey
+    # "type" value only
+    get '/lookup?type=doi'
+
+    assert_equal response.body, ''
+
+    # "identifier" value only
+    get '/lookup?identifier=10.1038/s41567-023-02305-y'
+
+    assert_equal response.body, ''
+  end
+
+  test 'lookup route returns HTML for valid parameters' do
+    VCR.use_cassette('libkey doi') do
+      get '/lookup?type=doi&identifier=10.1038/s41567-023-02305-y'
+
+      assert_response :success
+      assert_select 'a.button-primary', { count: 1 }
+    end
+
+    VCR.use_cassette('libkey pmid') do
+      get '/lookup?type=pmid&identifier=22110403'
+
+      assert_response :success
+      assert_select 'a.button-primary', { count: 1 }
+    end
+  end
+
+  test 'lookup for non-existent identifier returns blank' do
+    # Libkey responds here, so we have a cassette - but the response is empty
+    VCR.use_cassette('libkey nonexistent') do
+      get '/lookup?type=doi&identifier=foobar'
+
+      assert_response :success
+      assert_equal response.body, ''
+    end
+  end
+
+  test 'no response when either env var is not set' do
+    # No cassette because this never results in traffic to Libkey
+    ClimateControl.modify(LIBKEY_ID: nil) do
+      get '/lookup?type=doi&identifier=10.1038/s41567-023-02305-y'
+
+      assert_response :success
+      assert_equal response.body, ''
+    end
+
+    ClimateControl.modify(LIBKEY_KEY: nil) do
+      get '/lookup?type=doi&identifier=10.1038/s41567-023-02305-y'
+
+      assert_response :success
+      assert_equal response.body, ''
+    end
+  end
+end

test/models/libkey_test.rb

@@ -0,0 +1,100 @@
+require 'test_helper'
+
+class LibkeyMockResponse
+  attr_reader :status
+
+  def initialize(status, body)
+    @status = status
+    @body = body
+  end
+
+  def to_s
+    @body
+  end
+end
+
+class LibkeyConnectionError
+  def timeout(_)
+    self
+  end
+
+  def get(_url)
+    raise HTTP::ConnectionError, 'forced connection failure'
+  end
+end
+
+class LibkeyParsingError
+  def timeout(_)
+    self
+  end
+
+  def get(_url)
+    LibkeyMockResponse.new(200, 'This is not valid json')
+  end
+end
+
+class LibkeyTest < ActiveSupport::TestCase
+  test 'enabled? method returns true if both env are set' do
+    ClimateControl.modify(LIBKEY_ID: 'foo', LIBKEY_KEY: 'bar') do
+      assert Libkey.enabled?
+    end
+  end
+
+  test 'enabled? method returns false if either env not set' do
+    ClimateControl.modify(LIBKEY_ID: nil) do
+      refute Libkey.enabled?
+    end
+
+    ClimateControl.modify(LIBKEY_KEY: nil) do
+      refute Libkey.enabled?
+    end
+  end
+
+  test 'lookup does nothing with a type other than "doi" or "pmid"' do
+    refute Libkey.lookup(type: 'foo', identifier: 'foobar')
+  end
+
+  test 'lookup does work with any identifier value' do
+    VCR.use_cassette('libkey nonexistent') do
+      result = Libkey.lookup(type: 'doi', identifier: 'foobar')
+
+      refute result
+    end
+  end
+
+  test 'lookup gets a valid response for DOIs' do
+    VCR.use_cassette('libkey doi') do
+      result = Libkey.lookup(type: 'doi', identifier: '10.1038/s41567-023-02305-y')
+
+      assert_instance_of Hash, result
+      assert_equal result.keys, %i[link text type]
+    end
+  end
+
+  test 'lookup gets a valid response for PMIDs' do
+    VCR.use_cassette('libkey pmid') do
+      result = Libkey.lookup(type: 'pmid', identifier: '22110403')
+
+      assert_instance_of Hash, result
+      assert_equal result.keys, %i[link text type]
+    end
+  end
+
+  test 'libkey model catches connection errors' do
+    libkey_client = LibkeyConnectionError.new
+
+    result = Libkey.lookup(type: 'doi', identifier: '10.1038/s41567-023-02305-y', libkey_client:)
+
+    assert_instance_of Hash, result
+    assert_equal 'A connection error has occurred', result['error']
+  end
+
+  test 'libkey model catches parsing errors' do
+    libkey_client = LibkeyParsingError.new
+
+    result = Libkey.lookup(type: 'doi', identifier: '10.1038/s41567-023-02305-y', libkey_client:)
+
+    assert_instance_of Hash, result
+    assert_equal 'A parsing error has occurred', result['error']
+  end
+end

test/test_helper.rb

@@ -29,6 +29,8 @@
   config.filter_sensitive_data('FAKE_TACOS_HOST') { ENV.fetch('TACOS_HOST').to_s }
   config.filter_sensitive_data('FAKE_TACOS_SOURCE') { ENV.fetch('TACOS_SOURCE').to_s }
   config.filter_sensitive_data('http://FAKE_TACOS_HOST/graphql/') { ENV.fetch('TACOS_URL').to_s }
+  config.filter_sensitive_data('FAKE_LIBKEY_ID') { ENV.fetch('LIBKEY_ID').to_s }
+  config.filter_sensitive_data('FAKE_LIBKEY_KEY') { ENV.fetch('LIBKEY_KEY').to_s }
 end
 
 module ActiveSupport