berkeley_library-tind 0.4.0

data/lib/berkeley_library/tind/api/api_exception.rb

@@ -0,0 +1,131 @@
+require 'net/http/status'
+
+module BerkeleyLibrary
+  module TIND
+    module API
+      # Wrapper for network-related exceptions.
+      class APIException < StandardError
+        # @return [String, nil] the request URI, if any
+        attr_reader :url
+
+        # @return [Hash, nil] the API query parameters, if any
+        attr_reader :params
+
+        # @return [Integer, nil] the numeric HTTP status code, if any
+        attr_reader :status_code
+
+        # @return [String, nil] the HTTP status message, if any
+        attr_reader :status_message
+
+        # @return [RestClient::Response, nil] the response, if any
+        attr_reader :response
+
+        # Initializes a new APIException.
+        #
+        # @option opts [String] :msg the exception message (if not present, a default message will be constructed)
+        # @option opts [String] :url the request URL, if any
+        # @option opts [Hash] :params the query or form parameters, if any
+        # @option opts [Integer] :status_code the numeric HTTP status code, if any
+        # @option opts [String] :status_message a human-readable string representation of the HTTP status
+        #   (if not present, a default will be constructed)
+        # @option opts [RestClient::Response] :response the HTTP response, if any
+        def initialize(msg, **opts)
+          super(msg)
+
+          @url = opts[:url].to_s if opts.key?(:url)
+          @params = opts[:params]
+          @status_code, default_status_message = format_status(opts[:status_code])
+          @status_message = opts[:status_message] || default_status_message
+          @response = opts[:response]
+        end
+
+        def body
+          return @body if instance_variable_defined?(:@body)
+
+          @body = response && response.body
+        end
+
+        private
+
+        def format_status(status_code)
+          return unless (numeric_status = Integer(status_code, exception: false))
+
+          status_name = Net::HTTP::STATUS_CODES[numeric_status]
+          default_status_message = [numeric_status, status_name].compact.join(' ')
+
+          [numeric_status, default_status_message]
+        end
+
+        class << self
+          # @param ex [Exception] the exception to wrap
+          # @option opts [String] :msg the exception message (if not present, a default message will be constructed)
+          # @option opts [String] :url the request URL, if any
+          # @option opts [Hash] :params the query or form parameters, if any
+          # @option opts [String] :msg_context context information to prepend to the default message
+          def wrap(ex, **opts)
+            raise ArgumentError, "Can't wrap a nil error" unless ex
+
+            msg = opts[:msg] || message_from(ex, opts[:url], opts[:params], opts[:detail])
+            options = format_options(ex, opts[:url], opts[:params])
+            APIException.new(msg, **options)
+          end
+
+          private
+
+          def format_options(ex, url, params)
+            {}.tap do |opts|
+              opts[:url] = url if url
+              opts[:params] = params if params
+              next unless %i[http_code message response].all? { |f| ex.respond_to?(f) }
+
+              opts[:status_code] = ex.http_code
+              opts[:status_message] = ex.message
+              opts[:response] = ex.response
+            end
+          end
+
+          def message_from(ex, url, params, detail)
+            ''.tap do |msg|
+              msg << "#{detail}: " if detail
+              msg << (url ? "#{API.format_request(url, params)} returned #{ex}" : ex.to_s)
+            end
+          end
+        end
+      end
+
+      # Exception raised when the API key is nil or blank.
+      #
+      # NOTE: TIND incorrectly returns 403 Forbidden in this case, but we don't even bother
+      # to ask, we just simulate a 401.
+      class APIKeyNotSet < APIException
+        # @param endpoint_uri [URI] the endpoint URI
+        # @param params [Hash, nil] the query parameters
+        def initialize(endpoint_uri, params)
+          request_str = API.format_request(endpoint_uri, params)
+          super("#{request_str} failed; API key not set", status_code: 401)
+        end
+      end
+
+      # Exception raised when the TIND base URI is nil or blank.
+      class BaseURINotSet < APIException
+        # @param endpoint [String, Symbol] the endpoint
+        # @param params [Hash, nil] the query parameters
+        def initialize(endpoint, params)
+          msg = BaseURINotSet.format_message(endpoint, params)
+          super(msg, status_code: 404)
+        end
+
+        class << self
+          def format_message(endpoint, params)
+            "request to endpoint #{endpoint.inspect}".tap do |msg|
+              if (query_string = API.format_query(params))
+                msg << " with query #{query_string}"
+              end
+              msg << ' failed; base URI not set'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/tind/api/collection.rb

@@ -0,0 +1,82 @@
+require 'json'
+require 'berkeley_library/util/logging'
+require 'berkeley_library/tind/api/api_exception'
+
+module BerkeleyLibrary
+  module TIND
+    module API
+      class Collection
+        attr_reader :name, :nb_rec, :children, :translations
+        alias size nb_rec
+
+        def initialize(name, nb_rec, children, translations)
+          @name = name
+          @nb_rec = nb_rec
+          @children = children
+          @translations = translations
+        end
+
+        def name_en
+          return unless (names = translations['name'])
+
+          names['en']
+        end
+
+        def each_descendant(include_self: false, &block)
+          yield self if include_self
+
+          children.each { |c| c.each_descendant(include_self: include_self, &block) }
+        end
+
+        class << self
+          include BerkeleyLibrary::Logging
+
+          ENDPOINT = 'collections'.freeze
+
+          def all
+            json = API.get(ENDPOINT, depth: 100)
+            all_from_json(json)
+          rescue API::APIException => e
+            logger.error(e)
+            []
+          end
+
+          def each_collection(&block)
+            return to_enum(:each_collection) unless block_given?
+
+            all.each { |c| c.each_descendant(include_self: true, &block) }
+          end
+
+          # Returns an array of collection tree roots, which can be traversed
+          # with {Collection#each_descendant}.
+          #
+          # @return [Array<Collection>] an array of top-level collections
+          def all_from_json(json)
+            ensure_hash(json).map do |name, attrs|
+              translations = attrs['translations']
+              Collection.new(
+                name,
+                attrs['nb_rec'],
+                all_from_json(attrs['children']),
+                translations
+              )
+            end
+          end
+
+          private
+
+          def ensure_hash(json)
+            return {} unless json
+            return json if hash_like?(json)
+
+            JSON.parse(json)
+          end
+
+          def hash_like?(h)
+            h.respond_to?(:each_key) && h.respond_to?(:each_value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/tind/api/date_range.rb

@@ -0,0 +1,67 @@
+require 'berkeley_library/util/times'
+require 'berkeley_library/tind/config'
+
+module BerkeleyLibrary
+  module TIND
+    module API
+      class DateRange
+        FORMAT = '%Y-%m-%d %H:%M:%S'.freeze
+
+        attr_reader :from_time, :until_time
+
+        def initialize(from_time:, until_time:, mtime: false)
+          @from_time, @until_time = DateRange.ensure_valid_range(from_time, until_time)
+          @mtime = mtime
+        end
+
+        def mtime?
+          @mtime
+        end
+
+        def to_params
+          { d1: format_param(from_time), d2: format_param(until_time) }.tap do |params|
+            params[:dt] = 'm' if mtime?
+          end
+        end
+
+        alias eql ==
+
+        def ==(other)
+          return false unless other.class == self.class
+
+          [from_time, until_time] == [other.from_time, other.until_time]
+        end
+
+        class << self
+          def from_range(range)
+            DateRange.new(from_time: range.first, until_time: range.last)
+          end
+
+          def ensure_date_range(date_range)
+            return unless date_range
+            return date_range if date_range.is_a?(DateRange)
+            return DateRange.from_range(date_range) if date_range.respond_to?(:first) && date_range.respond_to?(:last)
+
+            raise ArgumentError, "Can't convert #{date_range.inspect} to #{DateRange}"
+          end
+
+          def ensure_valid_range(from_time, until_time)
+            ftime, utime = [from_time, until_time].map { |t| BerkeleyLibrary::Util::Times.ensure_utc(t) }
+            return [ftime, utime] if ftime <= utime
+
+            raise ArgumentError, "Not a valid range: #{from_time.inspect}..#{until_time.inspect}"
+          end
+        end
+
+        private
+
+        def format_param(t)
+          tz = BerkeleyLibrary::TIND::Config.timezone
+          t_utc = BerkeleyLibrary::Util::Times.ensure_utc(t) # just to be sure
+          t_local = tz.utc_to_local(t_utc)
+          t_local.strftime(FORMAT)
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/tind/api/format.rb

@@ -0,0 +1,32 @@
+require 'typesafe_enum'
+
+module BerkeleyLibrary
+  module TIND
+    module API
+      class Format < TypesafeEnum::Base
+        %i[ID XML FILES JSON].each { |fmt| new(fmt) }
+
+        def to_s
+          # noinspection RubyYardReturnMatch
+          value
+        end
+
+        def to_str
+          value
+        end
+
+        class << self
+          def ensure_format(format)
+            return unless format
+            return format if format.is_a?(Format)
+
+            fmt = Format.find_by_value(format.to_s.downcase)
+            return fmt if fmt
+
+            raise ArgumentError, "Unknown #{Format}: #{format.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/tind/api/search.rb

@@ -0,0 +1,100 @@
+require 'berkeley_library/util/logging'
+require 'berkeley_library/tind/marc/xml_reader'
+require 'berkeley_library/tind/api/date_range'
+require 'berkeley_library/tind/api/format'
+
+module BerkeleyLibrary
+  module TIND
+    module API
+      class Search
+        include BerkeleyLibrary::Logging
+
+        attr_reader :collection, :pattern, :index, :date_range, :format
+
+        def initialize(collection: nil, pattern: nil, index: nil, date_range: nil, format: Format::XML)
+          raise ArgumentError, 'Search requires a collection' unless collection
+
+          @collection = collection
+          @pattern = pattern
+          @index = index
+          @date_range = DateRange.ensure_date_range(date_range)
+          @format = Format.ensure_format(format)
+        end
+
+        # rubocop: disable Metrics/AbcSize
+        def params
+          @params ||= {}.tap do |params|
+            params[:c] = collection if collection
+            params[:p] = pattern if pattern
+            params[:f] = index if index
+            params.merge!(date_range.to_params) if date_range
+            params[:format] = self.format.to_s if self.format
+          end
+        end
+        # rubocop: enable Metrics/AbcSize
+
+        # Performs this search and returns the results as array.
+        # @return [Array<MARC::Record>] the results
+        def results
+          each_result.to_a
+        end
+
+        # Iterates over the records returned by this search.
+        # @overload each_result(freeze: false, &block)
+        #   Yields each record to the provided block.
+        #   @param freeze [Boolean] whether to freeze each record before yielding.
+        #   @yieldparam marc_record [MARC::Record] each record
+        #   @return [self]
+        # @overload each_result(freeze: false)
+        #   Returns an enumerator of the records.
+        #   @param freeze [Boolean] whether to freeze each record before yielding.
+        #   @return [Enumerable<MARC::Record>] the records
+        def each_result(freeze: false, &block)
+          return to_enum(:each_result, freeze: freeze) unless block_given?
+
+          perform_search(freeze: freeze, &block)
+          self
+        end
+
+        private
+
+        def perform_search(search_id: nil, freeze: false, &block)
+          logger.info("perform_search(search_id: #{search_id.inspect})")
+          params = search_id ? self.params.merge(search_id: search_id) : self.params
+          next_search_id = perform_single_search(params, freeze, &block)
+          perform_search(search_id: next_search_id, freeze: freeze, &block) if next_search_id
+        end
+
+        def perform_single_search(params, freeze, &block)
+          API.get(:search, params) do |body|
+            process_body(body, freeze, &block)
+          ensure
+            body.close
+          end
+        rescue APIException => e
+          return nil if empty_result?(e)
+
+          raise
+        end
+
+        def process_body(body, freeze, &block)
+          xml_reader = BerkeleyLibrary::TIND::MARC::XMLReader.read(body, freeze: freeze)
+          xml_reader.each(&block)
+          logger.debug("yielded #{xml_reader.records_yielded} of #{xml_reader.total} records")
+          logger.debug("next search ID: #{xml_reader.search_id}")
+          xml_reader.search_id if xml_reader.records_yielded > 0
+        end
+
+        def empty_result?(api_ex)
+          return false unless api_ex.status_code == 500
+          return false unless (body = api_ex.body)
+          return false unless (result = JSON.parse(body, symbolize_names: true))
+
+          result[:success] == false && result[:error].include?('0 values')
+        rescue JSON::ParserError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/tind/config.rb

@@ -0,0 +1,103 @@
+require 'berkeley_library/util/uris'
+require 'berkeley_library/tind/module_info'
+
+require 'tzinfo'
+
+module BerkeleyLibrary
+  module TIND
+    module Config
+
+      # The environment variable from which to read the TIND API key.
+      ENV_TIND_API_KEY = 'LIT_TIND_API_KEY'.freeze
+
+      # The root URL for the TIND installation
+      ENV_TIND_BASE_URL = 'LIT_TIND_BASE_URL'.freeze
+
+      DEFAULT_TZID = 'America/Los_Angeles'.freeze
+      DEFAULT_USER_AGENT = "#{ModuleInfo::NAME} #{ModuleInfo::VERSION} (#{ModuleInfo::HOMEPAGE})".freeze
+
+      class << self
+        include BerkeleyLibrary::Util::URIs
+
+        # Sets the TIND API key.
+        # @param value [String] the API key.
+        attr_writer :api_key
+
+        # Gets the TIND API key.
+        # @return [String, nil] the TIND API key, or `nil` if not set.
+        def api_key
+          @api_key ||= default_tind_api_key
+        end
+
+        def base_uri
+          @base_uri ||= default_tind_base_uri
+        end
+
+        def base_uri=(value)
+          @base_uri = uri_or_nil(value)
+        end
+
+        def timezone
+          @timezone ||= default_timezone
+        end
+
+        def timezone=(value)
+          raise ArgumentError, "Not a #{TZInfo::Timezone}" unless value.respond_to?(:utc_to_local)
+
+          @timezone = value
+        end
+
+        def user_agent
+          @user_agent || DEFAULT_USER_AGENT
+        end
+
+        def user_agent=(value)
+          raise ArgumentError, 'TIND firewall rules require a user agent' if blank?(value)
+
+          @user_agent = value
+        end
+
+        def blank?(v)
+          v.nil? || v.to_s.strip.empty?
+        end
+
+        private
+
+        def default_timezone
+          TZInfo::Timezone.get(Config::DEFAULT_TZID)
+        end
+
+        def default_tind_api_key
+          ENV[Config::ENV_TIND_API_KEY] || rails_tind_api_key
+        end
+
+        def default_tind_base_uri
+          return unless (base_url = ENV[Config::ENV_TIND_BASE_URL] || rails_tind_base_uri)
+
+          uri_or_nil(base_url)
+        end
+
+        def rails_tind_base_uri
+          return unless (rails_config = self.rails_config)
+          return unless rails_config.respond_to?(:tind_base_uri)
+
+          rails_config.tind_base_uri
+        end
+
+        def rails_tind_api_key
+          return unless (rails_config = self.rails_config)
+          return unless rails_config.respond_to?(:tind_api_key)
+
+          rails_config.tind_api_key
+        end
+
+        def rails_config
+          return unless defined?(Rails)
+          return unless (app = Rails.application)
+
+          app.config
+        end
+      end
+    end
+  end
+end