aspire 0.1.0

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/aspire.gemspec

@@ -0,0 +1,40 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'aspire/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'aspire'
+  spec.version       = Aspire::VERSION
+  spec.authors       = ['Lancaster University Library']
+  spec.email         = ['library.dit@lancaster.ac.uk']
+
+  spec.summary       = 'Ruby interface to the Talis Aspire API'
+  spec.description   = 'This gem provides a Ruby interface for working with' \
+                       'the Talis Aspire API.'
+  spec.homepage      = 'https://github.com/lulibrary/aspire'
+  spec.license       = 'MIT'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'logglier', '~> 0.2'
+  spec.add_dependency 'loofah', '~> 2.0'
+  spec.add_dependency 'rest-client', '~> 2.0'
+  spec.add_dependency 'sentry-raven', '~> 2.6'
+  spec.add_dependency 'clamp', '~> 1.1'
+  spec.add_dependency 'dotenv', '~> 2.2'
+
+  spec.add_development_dependency 'byebug', '~> 9.0'
+  spec.add_development_dependency 'bundler', '~> 1.14'
+  spec.add_development_dependency 'dotenv', '~> 2.2'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rubocop', '~> 0.49'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'minitest-reporters', '~> 1.1'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "aspire"
+
+# 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(__FILE__)

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/entrypoint.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+
+TIME_PERIOD=${TIME_PERIOD:-''}
+STATUS=${STATUS:-''}
+PRIVACY_CONTROL=${PRIVACY_CONTROL:-''}
+LIST_URL=${LIST_URL:-''}
+LANG=en_US.UTF-8
+LANGUAGE=en_US.UTF-8
+LC_ALL=en_US.UTF-8
+
+build-cache -t "${TIME_PERIOD}" -s "${STATUS}" -p "${PRIVACY_CONTROL}" -l "${LIST_URL}" -f

data/exe/build-cache

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'aspire'
+require 'raven'
+
+unless ENV['SENTRY_DSN'].nil? || ENV['SENTRY_DSN'].empty?
+  Raven.configure do |config|
+    config.dsn = ENV['SENTRY_DSN']
+  end
+end
+
+Aspire::CLI::CacheBuilder.run

data/lib/aspire.rb

@@ -0,0 +1,11 @@
+require 'aspire/api'
+require 'aspire/caching'
+require 'aspire/object'
+require 'aspire/util'
+require 'aspire/version'
+require 'aspire/cli/cache_builder'
+
+
+module Aspire
+  # Your code goes here...
+end

data/lib/aspire/api.rb

@@ -0,0 +1,2 @@
+require 'aspire/api/json'
+require 'aspire/api/linked_data'

data/lib/aspire/api/base.rb

@@ -0,0 +1,198 @@
+require 'json'
+require 'uri'
+
+require 'rest-client'
+
+require 'retry'
+
+module Aspire
+  module API
+    # The base class for Aspire API wrappers
+    class Base
+      # Domain names
+      TALIS_DOMAIN = 'talis.com'.freeze
+      ASPIRE_DOMAIN = "rl.#{TALIS_DOMAIN}".freeze
+      ASPIRE_AUTH_DOMAIN = "users.#{TALIS_DOMAIN}".freeze
+
+      # The default URL scheme
+      SCHEME = 'http'.freeze
+
+      # SSL options
+      SSL_OPTS = %i[ssl_ca_file ssl_ca_path ssl_cert_store].freeze
+
+      # @!attribute [rw] logger
+      #   @return [Logger] a logger for activity logging
+      attr_accessor :logger
+
+      # @!attribute [rw] ssl
+      #   @return [Hash] SSL options
+      attr_accessor :ssl
+
+      # @!attribute [rw] tenancy_code
+      #   @return [String] the Aspire short tenancy code
+      attr_accessor :tenancy_code
+
+      # @!attribute [rw] timeout
+      #   @return [Integer] the timeout period in seconds for API calls
+      attr_accessor :timeout
+
+      # Initialises a new API instance
+      # @param tenancy_code [String]
+      # @option opts [Logger] :logger the API activity logger
+      # @option opts [Integer] :timeout the API timeout in seconds
+      # @option opts [String] :ssl_ca_file the certificate authority filename
+      # @option opts [String] :ssl_ca_path the certificate authority directory
+      # @option opts [String] :ssl_cert_store the certificate authority store
+      def initialize(tenancy_code, **opts)
+        self.logger = opts[:logger]
+        self.tenancy_code = tenancy_code
+        self.timeout = opts[:timeout] || 0
+        # Retry options
+        initialize_retry(opts)
+        # SSL options
+        initialize_ssl(opts)
+        # Set the RestClient logger
+        RestClient.log = logger if logger
+      end
+
+      # Returns a full API URL from a partial path
+      # @abstract Subclasses must implement this method
+      # @param path [String] a full or partial API URL
+      # @return [String] the full API URL
+      def api_url(path)
+        path
+      end
+
+      private
+
+      # Calls an Aspire API endpoint and processes the response.
+      # Keyword parameters are passed directly to the REST client
+      # @return [(RestClient::Response, Hash)] the REST client response and
+      #   parsed JSON data from the response
+      def call_api(**rest_options)
+        @retry.do do
+          res = RestClient::Request.execute(**rest_options)
+          json = res && !res.empty? ? ::JSON.parse(res.to_s) : nil
+          call_api_response(res) if respond_to?(:call_api_response)
+          [res, json]
+        end
+      end
+
+      # Returns the HTTP headers for an API call
+      # @param headers [Hash] optional headers to add to the API call
+      # @param params [Hash] query string parameters for the API call
+      # @return [Hash] the HTTP headers
+      def call_rest_headers(headers, params)
+        rest_headers = {}.merge(headers || {})
+        rest_headers[:params] = params if params && !params.empty?
+        rest_headers
+      end
+
+      # Returns the REST client options for an API call
+      # @param path [String] the path of the API call
+      # @param headers [Hash<String, String>] HTTP headers for the API call
+      # @param options [Hash<String, Object>] options for the REST client
+      # @param params [Hash<String, String>] query string parameters
+      # @param payload [String, nil] the data to post to the API call
+      # @return [Hash] the REST client options
+      def call_rest_options(path, headers: nil, options: nil, params: nil,
+                            payload: nil)
+        rest_headers = call_rest_headers(headers, params)
+        rest_options = {
+          headers: rest_headers,
+          url: api_url(path)
+        }
+        common_rest_options(rest_options)
+        rest_options[:payload] = payload if payload
+        rest_options.merge!(options) if options
+        rest_options[:method] ||= payload ? :post : :get
+        rest_options
+      end
+
+      # Sets the REST client options common to all API calls
+      # @param rest_options [Hash] the REST client options
+      # @return [Hash] the REST client options
+      def common_rest_options(rest_options)
+        SSL_OPTS.each { |opt| rest_options[opt] = ssl[opt] if ssl[opt] }
+        rest_options[:timeout] = timeout > 0 ? timeout : nil
+        rest_options
+      end
+
+      # Initialises retry options
+      # @param opts [Hash] the options hash
+      # @return [void]
+      def initialize_retry(opts)
+        @retry = Retry::Engine.new(delay: opts[:retry_delay] || 5,
+                                   exceptions: initialize_retry_exceptions,
+                                   handlers: initialize_retry_handlers,
+                                   tries: opts[:retries] || 5)
+      end
+
+      # Returns a hash of retriable exceptions
+      # @return [Hash<Exception|Symbol, Boolean>] the retriable exceptions
+      def initialize_retry_exceptions
+        [
+          RestClient::ExceptionWithResponse,
+          RestClient::ServerBrokeConnection,
+          RestClient::Exceptions::Timeout
+        ].push(*Retry::Exceptions::SOCKET_EXCEPTIONS)
+      end
+
+      # Returns a hash of retry handlers
+      # @return [Hash<Exception|Symbol, Proc>] the retry handlers
+      def initialize_retry_handlers
+        {
+          :default => proc { |e, _t| log_exception(e) },
+          :retry => proc { |_e, t| logger.debug("Retrying (#{t} tries left)") },
+          RestClient::ExceptionWithResponse => proc do |e, _t|
+            log_exception(e, debug: "Response: #{e}")
+            # json = ::JSON.parse(response.to_s) if response && !response.empty?
+            raise Retry::StopRetry.new([e.response, nil])
+          end
+        }
+      end
+
+      # Sets the SSL options
+      # @param opts [Hash] the options hash
+      def initialize_ssl(opts)
+        self.ssl = {}
+        SSL_OPTS.each { |opt| ssl[opt] = opts[opt] }
+      end
+
+      # Logs an exception
+      # @param e [Exception] the exception
+      # @param debug [String] extra debugging message
+      def log_exception(e, debug: nil)
+        return unless logger
+        logger.error(e.to_s)
+        logger.debug(e.backtrace.join('\n'))
+        logger.debug(debug) if debug
+      end
+
+      # Returns a URI instance for a URL, treating URLs without schemes or path
+      # components as host names
+      # @param url [String] the URL
+      # @return [URI] the URI instance
+      def uri(url)
+        url = URI.parse(url) unless url.is_a?(URI)
+        if url.host.nil? && url.scheme.nil?
+          url.host = url.path
+          url.path = ''
+        end
+        url.scheme ||= 'http'
+        url
+      rescue URI::InvalidComponentError, URI::InvalidURIError
+        nil
+      end
+
+      # Returns the host name of a URL, treating URLs without schemes or path
+      # components as host names
+      # @param url [String] the URL
+      # @return [String] the host name of the URL
+      def uri_host(url)
+        url = uri(url)
+        url ? url.host : nil
+      end
+    end
+  end
+end

data/lib/aspire/api/json.rb

@@ -0,0 +1,195 @@
+require 'base64'
+
+require_relative 'base'
+
+module Aspire
+  module API
+    # A wrapper class for the Aspire JSON API
+    class JSON < Base
+      # The default API root URL
+      API_ROOT = "https://#{ASPIRE_DOMAIN}".freeze
+
+      # The default authentication API root URL
+      API_ROOT_AUTH = "https://#{ASPIRE_AUTH_DOMAIN}/1/oauth/tokens".freeze
+
+      # @!attribute [rw] api_root
+      #   @return [String] the base URL of the Aspire JSON APIs
+      attr_accessor :api_root
+
+      # @!attribute [rw] api_root_auth
+      #   @return [String] the base URL of the Aspire Persona authentication API
+      attr_accessor :api_root_auth
+
+      # @!attribute [rw] api_version
+      #   @return [Integer] the version of the Aspire JSON APIs
+      attr_accessor :api_version
+
+      # @!attribute [rw] rate_limit
+      #   @return [Integer] the rate limit value from the most recent API call
+      attr_accessor :rate_limit
+
+      # @!attribute [rw] rate_remaining
+      #   @return [Integer] the rate remaining value from the most recent API
+      #     call (the number of calls remaining within the current limit period)
+      attr_accessor :rate_remaining
+
+      # @!attribute [rw] rate_reset
+      #   @return [Integer] the rate reset value from the most recent API call
+      #     (the time in seconds since the Epoch until the next limit period)
+      attr_accessor :rate_reset
+
+      # Initialises a new API instance
+      # @param api_client_id [String] the API client ID
+      # @param api_secret [String] the API secret associated with the client ID
+      # @param tenancy_code [String] the Aspire short tenancy code
+      # @param opts [Hash] API customisation options
+      # @option opts [String] :api_root the base URL of the Aspire JSON APIs
+      # @option opts [String] :api_root_auth the base URL of the Aspire Persona
+      #   authentication API
+      # @option opts [Integer] :api_version the version of the Aspire JSON APIs
+      # @option opts [Logger] :logger a logger for activity logging
+      # @option opts [Integer] :timeout the API call timeout period in seconds
+      # @return [void]
+      def initialize(api_client_id = nil, api_secret = nil, tenancy_code = nil,
+                     **opts)
+        super(tenancy_code, **opts)
+        @api_client_id = api_client_id
+        @api_secret = api_secret
+        @api_token = nil
+        self.api_root = opts[:api_root] || API_ROOT
+        self.api_root_auth = opts[:api_root_auth] || API_ROOT_AUTH
+        self.api_version = opts[:api_version] || 2
+        rate_limit
+      end
+
+      # Returns a full Aspire JSON API URL. Full URLs are returned as-is,
+      # partial endpoint paths are expanded with the API root, version and
+      # tenancy code.
+      # @param path [String] the full URL or partial endpoint path
+      # @return [String] the full JSON API URL
+      def api_url(path)
+        return path if path.include?('//')
+        "#{api_root}/#{api_version}/#{tenancy_code}/#{path}"
+      end
+
+      # Calls an Aspire JSON API method and returns the parsed JSON response
+      # Additional keyword parameters are passed as query string parameters
+      # to the API call.
+      # @param path [String] the path of the API call
+      # @param headers [Hash<String, String>] HTTP headers for the API call
+      # @param options [Hash<String, Object>] options for the REST client
+      # @param payload [String, nil] the data to post to the API call
+      # @return [Hash] the parsed JSON content from the API response
+      # @yield [response, data] Passes the REST client response and parsed JSON
+      #   hash to the block
+      # @yieldparam [RestClient::Response] the REST client response
+      # @yieldparam [Hash] the parsed JSON data from the response
+      def call(path, headers: nil, options: nil, payload: nil, **params)
+        rest_options = call_rest_options(path,
+                                         headers: headers, options: options,
+                                         payload: payload, params: params)
+        response, data = call_api_with_auth(**rest_options)
+        yield(response, data) if block_given?
+        data
+      end
+
+      private
+
+      # Returns an Aspire OAuth API token. New tokens are retrieved from the
+      #   Aspire Persona API and cached for subsequent API calls.
+      # @param refresh [Boolean] if true, force retrieval of a new token
+      # @return [String] the API token
+      def api_token(refresh = false)
+        # Return the cached token unless forcing a refresh
+        return @api_token unless @api_token.nil? || refresh
+        # Set the token to nil to indicate that there is no current valid token
+        # in case an exception is thrown by the API call.
+        @api_token = nil
+        # Get and return the API token
+        _response, data = call_api(**api_token_rest_options)
+        @api_token = data['access_token']
+      end
+
+      # Returns the HTTP Basic authentication token
+      # @return [String] the Basic authentication token
+      def api_token_authorization
+        Base64.strict_encode64("#{@api_client_id}:#{@api_secret}")
+      end
+
+      # Returns the HTTP headers for the token retrieval API call
+      def api_token_rest_headers
+        {
+          Authorization: "basic #{api_token_authorization}",
+          'Content-Type'.to_sym => 'application/x-www-form-urlencoded'
+        }
+      end
+
+      def api_token_rest_options
+        rest_options = {
+          headers: api_token_rest_headers,
+          payload: { grant_type: 'client_credentials' },
+          url: api_root_auth
+        }
+        common_rest_options(rest_options)
+        rest_options[:method] = :post
+        rest_options
+      end
+
+      # Returns true if the HTTP response is an authentication failure
+      # @param response [RestClient::Response] the REST client response
+      # @return [Boolean] true on authentication failure, false otherwise
+      def auth_failed(response)
+        response && response.code == 401
+      end
+
+      # Performs custom HTTP response processing
+      # @param response [RestClient::Response] the REST client response
+      # @return [void]
+      def call_api_response(response)
+        rate_limit(headers: response.headers)
+      end
+
+      # Calls an authenticated Aspire API endpoint and processes the response.
+      # The call is made first with the currently-cached authentication token.
+      # If this fails due to authentication, the token is refreshed and the call
+      # is repeated once with the new token.
+      # @see (#call_api)
+      def call_api_with_auth(**rest_options)
+        refresh = false
+        loop do
+          token = api_token(refresh)
+          rest_options[:headers]['Authorization'] = "Bearer #{token}"
+          response, data = call_api(**rest_options)
+          # Stop if we have a valid response or we've already tried to refresh
+          #   the token.
+          return response, data unless auth_failed(response) && !refresh
+          # The API token may have expired, try one more time with a new token
+          refresh = true
+        end
+      end
+
+      # Sets API rate-limit parameters
+      # @param headers [Hash] the HTTP response headers
+      # @param limit [Integer] the default rate limit
+      # @param remaining [Integer] the default remaining count
+      # @param reset [Integer] the default reset period timestamp
+      # @return [nil]
+      def rate_limit(headers: {}, limit: nil, remaining: nil, reset: nil)
+        reset = rate_limit_header(:reset, headers, reset)
+        self.rate_limit = rate_limit_header(:limit, headers, limit)
+        self.rate_remaining = rate_limit_header(:remaining, headers, remaining)
+        self.rate_reset = reset ? Time(reset) : nil
+      end
+
+      # Returns the numeric value of a rate-limit header
+      # @param header [String, Symbol] the header (minus x_ratelimit_ prefix)
+      # @param headers [Hash] the HTTP response headers
+      # @param default [Integer, nil] the default value if the header is missing
+      # @return [Integer, nil] the numeric value of the header
+      def rate_limit_header(header, headers, default)
+        value = headers["x_ratelimit_#{header}".to_sym]
+        value ? value.to_i : default
+      end
+    end
+  end
+end