aspire 0.1.0

data/lib/aspire/object/user.rb

@@ -0,0 +1,46 @@
+require 'aspire/object/base'
+
+module Aspire
+  module Object
+    # Represents a user profile in the Aspire API
+    class User < Base
+      # @!attribute [rw] email
+      #   @return [Array<String>] the list of email addresses for the user
+      attr_accessor :email
+
+      # @!attribute [rw] first_name
+      #   @return [String] the user's first name
+      attr_accessor :first_name
+
+      # @!attribute [rw] role
+      #   @return [Array<String>] the Aspire roles associated with the user
+      attr_accessor :role
+
+      # @!attribute [rw] surname
+      #   @return [String] the user's last name
+      attr_accessor :surname
+
+      # Initialises a new User instance
+      # @param uri [String] the URI of the user profile
+      # @param factory [Aspire::Object::Factory] the data object factory
+      # @param json [Hash] the user profile data from the Aspire JSON API
+      # @param ld [Hash] the user profile data from the Aspire linked data API
+      # @return [void]
+      def initialize(uri, factory, json: nil, ld: nil)
+        super(uri, factory)
+        json ||= {}
+        self.email = json['email']
+        self.first_name = json['firstName']
+        self.role = json['role']
+        self.surname = json['surname']
+      end
+
+      # Returns a string representation of the user profile (name and emails)
+      # @return [String] the string representation of the user profile
+      def to_s
+        emails = email.nil? || email.empty? ? '' : " <#{email.join('; ')}>"
+        "#{first_name} #{surname}#{emails}"
+      end
+    end
+  end
+end

data/lib/aspire/properties.rb

@@ -0,0 +1,20 @@
+module Aspire
+  # Aspire linked data API property names
+  module Properties
+    AIISO_CODE = 'http://purl.org/vocab/aiiso/schema#code'.freeze
+    AIISO_NAME = 'http://putl.org/vocab/aiiso/schema#name'.freeze
+    CREATED = 'http://purl.org/vocab/resourcelist/schema#created'.freeze
+    DESCRIPTION = 'http://purl.org/vocab/resourcelist/schema#description'
+                    .freeze
+    HAS_CREATOR = 'http://rdfs.org/sioc/spec/has_creator'.freeze
+    HAS_OWNER = 'http://purl.org/vocab/resourcelist/schema#hasOwner'.freeze
+    LAST_PUBLISHED = 'http://purl.org/vocab/resourcelist/schema#lastPublished'
+                       .freeze
+    LAST_UPDATED = 'http://purl.org/vocab/resourcelist/schema#lastUpdated'
+                     .freeze
+    NAME = 'http://rdfs.org/sioc/spec/name'.freeze
+    PUBLISHED_BY = 'http://purl.org/vocab/resourcelist/schema#publishedBy'
+                     .freeze
+    USED_BY = 'http://purl.org/vocab/resourcelist/schema#usedBy'.freeze
+  end
+end

data/lib/aspire/user_lookup.rb

@@ -0,0 +1,103 @@
+require 'csv'
+
+require 'aspire/enumerator/report_enumerator'
+require 'aspire/object/user'
+
+module Aspire
+  # Implements a hash of User instances indexed by URI
+  # The hash can be populated from an Aspire All User Profiles report CSV file
+  class UserLookup
+    # @!attribute [rw] store
+    #   @return [Object] a hash-like object mapping user URIs to their JSON data
+    attr_accessor :store
+
+    # Initialises a new UserLookup instance
+    # @see (Hash#initialize)
+    # @param filename [String] the filename of the CSV file to populate the hash
+    # @return [void]
+    def initialize(filename: nil, store: nil)
+      self.store = store || {}
+      load(filename) if filename
+    end
+
+    # Returns an Aspire::Object::User instance for a URI
+    # @param uri [String] the URI of the user
+    # @param factory [Aspire::Object::Factory] the data object factory
+    # @return [Aspire::Object::User] the user
+    def [](uri, factory = nil)
+      data = store[uri]
+      data.nil? ? nil : Aspire::Object::User.new(uri, factory, json: data)
+    end
+
+    # Populates the store from an All User Profiles report CSV file
+    # @param filename [String] the filename of the CSV file
+    # @return [void]
+    def load(filename = nil)
+      delim = /\s*;\s*/ # The delimiter for email and role lists
+      enum = Aspire::Enumerator::ReportEnumerator.new(filename).enumerator
+      enum.each do |row|
+        # Construct a JSON data structure for the user
+        uri = row[3]
+        data = csv_to_json_api(row, email_delim: delim, role_delim: delim)
+        csv_to_json_other(row, data)
+        # Store the JSON data in the lookup table
+        store[uri] = data
+      end
+    end
+
+    # Proxies missing methods to the store
+    # @param method [Symbol] the method name
+    # @param args [Array] the method arguments
+    # @param block [Proc] the code block
+    # @return [Object] the store method result
+    def method_missing(method, *args, &block)
+      super unless store.respond_to?(method)
+      store.public_send(method, *args, &block)
+    end
+
+    # Proxies missing method respond_to? to the store
+    # @param method [Symbol] the method name
+    # @param include_private [Boolean] if true, include private methods,
+    #   otherwise include only public methods
+    # @return [Boolean] true if the store supports the method, false otherwise
+    def respond_to_missing?(method, include_private = false)
+      store.respond_to?(method, include_private)
+    end
+
+    private
+
+    def csv_to_json(row)
+      # Recreate the Aspire user profile JSON API response from the CSV record
+      data = csv_to_json_api(row)
+      # Add other report fields which aren't part of the JSON API response
+      csv_to_json_other(row, data)
+    end
+
+    # Adds CSV fields which mirror the Aspire user profile JSON API fields
+    # @param row [Array] the fields from the All User Profiles report CSV
+    # @param data [Hash] the JSON representation of the user profile
+    # @return [Hash] the JSON data hash
+    def csv_to_json_api(row, data = {}, email_delim: nil, role_delim: nil)
+      data['email'] = (row[4] || '').split(email_delim)
+      data['firstName'] = row[0]
+      data['role'] = (row[7] || '').split(role_delim)
+      data['surname'] = row[1]
+      data['uri'] = row[3]
+      data
+    end
+
+    # Adds CSV fields which aren't part of the Aspire user profile JSON API
+    # @param row [Array] the fields from the All User Profiles report CSV
+    # @param data [Hash] the JSON representation of the user profile
+    # @return [Hash] the JSON data hash
+    def csv_to_json_other(row, data = {})
+      # The following fields are not present in the JSON API response but are in
+      # the All User Profiles report - they are included for completeness.
+      data['jobRole'] = row[5] || ''
+      data['lastLogin'] = row[8]
+      data['name'] = row[2] || ''
+      data['visibility'] = row[6] || ''
+      data
+    end
+  end
+end

data/lib/aspire/util.rb

@@ -0,0 +1,185 @@
+module Aspire
+  # Utility methods mixin
+  module Util
+    # Regular expression to parse a Linked Data API URI
+    LD_API_URI = Regexp.new('https?://(?<tenancy_host>[^/]*)/' \
+                            '(?<type>[^/]*)/' \
+                            '(?<id>[^/\.]*)' \
+                            '(\.(?<format>[^/]*))?' \
+                            '(/' \
+                            '(?<child_type>[^/.]*)' \
+                            '(/(?<child_id>[^/\.]*))?' \
+                            '(\.(?<child_format>[^/]*))?' \
+                            ')?(?<rest>.*)').freeze
+
+    # Returns true if the first URL is the child of the second URL
+    # @param url1 [Aspire::Caching::CacheEntry, String] the first URL
+    # @param url2 [Aspire::Caching::CacheEntry, String] the second URL
+    # @param api [Aspire::API::LinkedData] the API for generating canonical URLs
+    # @param strict [Boolean] if true, the URL must be a parent of this entry,
+    #   otherwise the URL must be a parent or the same as this entry
+    # @return [Boolean] true if the URL is a child of the cache entry, false
+    #   otherwise
+    def child_url?(url1, url2, api = nil, strict: false)
+      parent_url?(url2, url1, api, strict: strict)
+    end
+
+    # Returns a HH:MM:SS string given a Benchmark time
+    # @param benchmark_time [Benchmark:Tms] the Benchmark time object
+    # @return [String] the HH:HM:SS string
+    def duration(benchmark_time)
+      secs = benchmark_time.real
+      hours = secs / 3600
+      format('%2.2d:%2.2d:%2.2d', hours, hours % 60, secs % 60)
+    end
+
+    # Returns the ID of an object from its URL
+    # @param u [String] the URL of the API object
+    # @return [String] the object ID
+    def id_from_uri(u, parsed: nil)
+      parsed ||= parse_url(u)
+      parsed[:id]
+    end
+
+    # Returns true if URI is a list item
+    # @param uri [String] the URI
+    # @return [Boolean] true if the URI is a list item, otherwise false
+    def item?(uri)
+      uri.include?('/items/')
+    end
+
+    # Returns the data for a URI from a parsed linked data API response
+    # which may contain multiple objects
+    # @param uri [String] the URI of the object
+    # @param ld [Hash] the parsed JSON data from the Aspire linked data API
+    # @return [Hash] the parsed JSON data for the URI
+    def linked_data(uri, ld)
+      uri = linked_data_path(uri)
+      return nil unless uri && ld
+      # The URI used to retrieve the data may be the canonical URI or a
+      # tenancy aliases. We ignore the host part of the URIs and match just
+      # the path
+      ld.each { |u, data| return data if uri == linked_data_path(u) }
+      # No match was found
+      nil
+    end
+
+    # Returns the path of a URI
+    # @param uri [String] the URI
+    # @return [String, nil] the URI path or nil if invalid
+    def linked_data_path(uri)
+      URI.parse(uri).path
+    rescue URI::InvalidComponentError, URI::InvalidURIError
+      nil
+    end
+
+    # Returns true if URI is a list
+    # @param uri [String] the URI
+    # @return [Boolean] true if the URI is a list, otherwise false
+    def list?(uri)
+      uri.include?('/lists/')
+    end
+
+    # Returns true if a URL is a list URL, false otherwise
+    # @param u [String] the URL of the API object
+    # @return [Boolean] true if the URL is a list URL, false otherwise
+    def list_url?(u = nil, parsed: nil)
+      return false if (u.nil? || u.empty?) && parsed.nil?
+      parsed ||= parse_url(u)
+      child_type = parsed[:child_type]
+      parsed[:type] == 'lists' && (child_type.nil? || child_type.empty?)
+    end
+
+    # Returns true if URI is a module
+    # @param uri [String] the URI
+    # @return [Boolean] true if the URI is a module, otherwise false
+    def module?(uri)
+      uri.include?('/modules/')
+    end
+
+    # Returns true if the first URL is the parent of the second URL
+    # @param url1 [Aspire::Caching::CacheEntry, String] the first URL
+    # @param url2 [Aspire::Caching::CacheEntry, String] the second URL
+    # @param api [Aspire::API::LinkedData] the API for generating canonical URLs
+    # @param strict [Boolean] if true, the first URL must be a parent of the
+    #   second URL, otherwise the first URL must be a parent or the same as the
+    #   second.
+    # @return [Boolean] true if the URL has the same parent as this entry
+    def parent_url?(url1, url2, api = nil, strict: false)
+      u1 = url_for_comparison(url1, api, parsed: true)
+      u2 = url_for_comparison(url2, api, parsed: true)
+      # Both URLs must have the same parent
+      return false unless u1[:type] == u2[:type] && u1[:id] == u2[:id]
+      # Non-strict comparison requires only the same parent object
+      return true unless strict
+      # Strict comparison requires that this entry is a child of the URL
+      u1[:child_type].nil? && !u2[:child_type].nil? ? true : false
+    end
+
+    # Returns the components of an object URL
+    # @param url [String] the object URL
+    # @return [MatchData, nil] the URI components:
+    #   {
+    #     tenancy_host: tenancy root (server name),
+    #     type: type of primary object,
+    #     id: ID of primary object,
+    #     child_type: type of child object,
+    #     child_id: ID of child object
+    #   }
+    def parse_url(url)
+      url ? LD_API_URI.match(url) : nil
+    end
+
+    # Returns true if URI is a resource
+    # @param uri [String] the URI
+    # @return [Boolean] true if the URI is a resource, otherwise false
+    def resource?(uri)
+      uri.include?('/resources/')
+    end
+
+    # Returns true if URI is a section
+    # @param uri [String] the URI
+    # @return [Boolean] true if the URI is a section, otherwise false
+    def section?(uri)
+      uri.include?('/sections/')
+    end
+
+    # Returns a parsed or unparsed URL for comparison
+    # @param url [Aspire::Caching::CacheEntry, String] the URL
+    # @param api [Aspire::API::LinkedData] the API for generating canonical URLs
+    # @param parsed [Boolean] if true, return a parsed URL, otherwise return
+    #   an unparsed URL string
+    # @return [Aspire::Caching::CacheEntry, String] the URL for comparison
+    def url_for_comparison(url, api = nil, parsed: false)
+      if url.is_a?(MatchData) && parsed
+        url
+      elsif parsed && url.respond_to?(:parsed_url)
+        url.parsed_url
+      elsif !parsed && url.respond_to?(url)
+        url.url
+      else
+        result = api.nil? ? url.to_s : api.canonical_url(url.to_s)
+        parsed ? parse_url(result) : result
+      end
+    end
+
+    # Returns the path from the URL as a relative filename
+    def url_path
+      # Get the path component of the URL as a relative path
+      filename = URI.parse(url).path
+      filename.slice!(0) # Remove the leading /
+      # Return the path with '.json' extension if not already present
+      filename.end_with?('.json') ? filename : "#{filename}.json"
+    rescue URI::InvalidComponentError, URI::InvalidURIError
+      # Return nil if the URL is invalid
+      nil
+    end
+
+    # Returns true if URI is a section
+    # @param uri [String] the URI
+    # @return [Boolean] true if the URI is a section, otherwise false
+    def user?(uri)
+      uri.include?('/users/')
+    end
+  end
+end

data/lib/aspire/version.rb

@@ -0,0 +1,3 @@
+module Aspire
+  VERSION = '0.1.0'.freeze
+end

data/lib/retry.rb

@@ -0,0 +1,197 @@
+# Support for performing retriable operations
+module Retry
+  # Common exceptions suitable for retrying
+  module Exceptions
+    SOCKET_EXCEPTIONS = [
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EINTR,
+      Errno::EHOSTUNREACH,
+      Errno::ENETDOWN,
+      Errno::ENETUNREACH,
+      Errno::ENOBUFS,
+      Errno::ENOSR,
+      Errno::ETIMEDOUT,
+      IO::WaitReadable
+    ].freeze
+  end
+
+  # Retry handlers should raise this exception to stop retry processing and
+  # return the return value from the Retry.do method
+  class StopRetry < RuntimeError
+    attr_accessor :value
+    def initialize(value = nil)
+      self.value = value
+    end
+  end
+
+  # Support for repeatedly calling retriable operations
+  class Engine
+    attr_accessor :delay
+    attr_accessor :exceptions
+    attr_accessor :handlers
+    attr_accessor :tries
+
+    # Initialises a new Engine instance
+    # @param delay [Float] the default delay before retrying
+    # @param exceptions [Hash<Exception, Boolean>] the default retriable
+    #   exceptions
+    # @param handlers [Hash<Exception|Symbol, Proc>] the default exception
+    #   handlers
+    # @param tries [Integer, Proc] the default maximum number of tries or
+    #   a proc which accepts an Exception and returns true if a retry is allowed
+    #   or false if not
+    # @return [void]
+    def initialize(delay: nil, exceptions: nil, handlers: nil, tries: nil)
+      self.delay = delay.to_f
+      self.exceptions = exceptions || {}
+      self.handlers = handlers || {}
+      self.tries = tries
+    end
+
+    # Executes the class method do using instance default values
+    def do(delay: nil, exceptions: nil, handlers: nil, tries: nil, &block)
+      Retry.do(delay: delay || self.delay,
+               exceptions: exceptions || self.exceptions,
+               handlers: handlers || self.handlers,
+               tries: tries || self.tries,
+               &block)
+    end
+  end
+
+  # Executes the code block until it returns successfully, throws a
+  # non-retriable exception or some termination condition is met.
+  # @param delay [Float] the number of seconds to wait before retrying.
+  #   Positive values specify an exact delay, negative values specify a
+  #   random delay no longer than this value.
+  # @param exceptions [Hash<Exception, Boolean>] the hash of retriable
+  #   exceptions
+  # @param handlers [Hash<Exception|Symbol, Proc>] handlers to be invoked
+  #   when specific exceptions occur. A handler should accept the exception
+  #   and the number of tries remaining as arguments. It does not need to
+  #   re-raise its exception argument, but it may throw another exception
+  #   to prevent a retry.
+  # @param tries [Integer] the maximum number of tries
+  # @return [Object] the return value of the block
+  def self.do(delay: nil, exceptions: nil, handlers: nil, tries: nil)
+    yield if block_given?
+  rescue StandardError => exception
+    # Decrement the tries-remaining count if appropriate
+    tries -= 1 if tries.is_a?(Numeric)
+    # Handlers may raise StopRetry to force a return value from the method
+    # Check if the exception is retriable
+    retriable = retry?(exception, exceptions, tries)
+    begin
+      # Run the exception handler
+      # - this will re-raise the exception if it is not retriable
+      handle_exception(exception, handlers, tries, retriable)
+      # Run the retry handler and retry
+      handle_retry(exception, handlers, tries, retriable, delay)
+      retry
+    rescue StopRetry => exception
+      # Force a return value from the handler
+      exception.value
+    end
+  end
+
+  # Executes a handler for an exception
+  # @param exception [Exception] the exception
+  # @param handlers [Hash<Exception|Symbol, Proc>] the exception handlers
+  # @param tries [Integer] the number of tries remaining
+  # @param retriable [Boolean] true if the exception is retriable, false if not
+  # @return [Object] the return value of the handler, or nil if no handler
+  #   was executed
+  def self.handle_exception(exception, handlers, tries, retriable)
+    # Execute the general exception handler
+    handler(exception, handlers, tries, retriable, :all)
+    # Execute the exception-specific handler
+    handler(exception, handlers, tries, retriable)
+    # Re-raise the exception if not retriable
+    raise exception unless retriable
+  end
+
+  # Executes the retry handler
+  # @param exception [Exception] the exception
+  # @param handlers [Hash<Exception|Symbol, Proc>] the exception handlers
+  # @param tries [Integer] the number of tries remaining
+  # @param retriable [Boolean] true if the exception is retriable, false if not
+  # @param delay [Float] the number of seconds to wait before retrying
+  def self.handle_retry(exception, handlers, tries, retriable, delay)
+    # Wait for the specified delay
+    wait(delay) unless delay.zero?
+    # Return the result of the retry handler
+    handler(exception, handlers, tries, retriable, :retry)
+  end
+
+  # Executes the specified handler
+  # @param exception [Exception] the exception
+  # @param handlers [Hash<Exception|Symbol, Proc>] the exception handlers
+  # @param tries [Integer] the number of tries remaining
+  # @param retriable [Boolean] true if the exception is retriable, false if not
+  # @param name [Symbol] the handler name, defaults to the exception class
+  # @return [Object] the return value of the handler, or nil if no handler
+  #   was executed
+  def self.handler(exception, handlers, tries, retriable, name = nil)
+    handler = nil
+    if name.nil?
+      # Find the handler for the exception class
+      handlers.each do |e, h|
+        next unless e.is_a?(Class) && exception.is_a?(e)
+        handler = h
+        break
+      end
+      # Use the default handler if no match was found
+      handler ||= handlers[:default]
+    else
+      # Use the named handler, do not use the default if not found
+      handler = handlers[name]
+    end
+    handler ? handler.call(exception, tries, retriable) : nil
+  end
+
+  # Returns true if the exception instance is retriable, false if not
+  # @param exception [Exception] the exception instance
+  # @param tries [Integer, Proc] the number of tries remaining or a proc
+  #   determining whether tries remain
+  # @return [Boolean] true if the exception is retriable, false if not
+  def self.retry?(exception, exceptions, tries)
+    # Return false if there are no more tries remaining
+    return false unless tries_remain?(exception, tries)
+    # Return true if the exception matches a retriable exception class
+    exceptions.each { |e| return true if exception.is_a?(e) }
+    # The exception didn't match any retriable classes
+    false
+  end
+
+  # Returns true if there are tries remaining
+  # @param exception [Exception] the exception instance
+  # @param tries [Integer, Proc] the number of tries remaining or a proc
+  #   determining whether tries remain
+  def self.tries_remain?(exception, tries)
+    # If tries is numeric, this is the number of tries remaining
+    return false if tries.is_a?(Numeric) && tries.zero?
+    # If tries has a #call method, this should return true to allow a retry or
+    # false to raise the exception
+    return false if tries.respond_to?(:call) && !tries.call(exception)
+    # Otherwise allow a retry
+    true
+  end
+
+  # Waits for the specified number of seconds. If delay is positive, sleep
+  # for that period. If delay is negative, sleep for a random time up to
+  # that duration.
+  # @param delay [Float] the number of seconds to wait before retrying
+  # @return [void]
+  def self.wait(delay)
+    sleep(delay > 0 ? delay : Random.rand(-delay))
+  end
+
+  class << self
+    private :handle_exception
+    private :handle_retry
+    private :handler
+    private :retry?
+    private :tries_remain?
+    private :wait
+  end
+end