nexus_mods 0.1.1 → 0.3.0

data/lib/nexus_mods/api_client.rb

@@ -0,0 +1,182 @@
+require 'fileutils'
+require 'faraday'
+require 'faraday-http-cache'
+require 'nexus_mods/file_cache'
+require 'nexus_mods/cacheable_api'
+
+class NexusMods
+
+  # Base class handling HTTP calls to the NexusMods API.
+  # Handle caching if needed.
+  class ApiClient
+
+    include CacheableApi
+
+    # Constructor
+    #
+    # Parameters::
+    # * *api_key* (String or nil): The API key to be used, or nil for another authentication [default: nil]
+    # * *http_cache_file* (String): File used to store the HTTP cache, or nil for no cache [default: "#{Dir.tmpdir}/nexus_mods_http_cache.json"]
+    # * *api_cache_expiry* (Hash<Symbol,Integer>): Expiry times in seconds, per expiry key. Possible keys are:
+    #   * *games*: Expiry associated to queries on games [default: 1 day]
+    #   * *mod*: Expiry associated to queries on mod [default: 1 day]
+    #   * *mod_files*: Expiry associated to queries on mod files [default: 1 day]
+    # * *api_cache_file* (String): File used to store the NexusMods API cache, or nil for no cache [default: "#{Dir.tmpdir}/nexus_mods_api_cache.json"]
+    # * *logger* (Logger): The logger to be used for log messages [default: Logger.new(STDOUT)]
+    def initialize(
+      api_key: nil,
+      http_cache_file: "#{Dir.tmpdir}/nexus_mods_http_cache.json",
+      api_cache_expiry: DEFAULT_API_CACHE_EXPIRY,
+      api_cache_file: "#{Dir.tmpdir}/nexus_mods_api_cache.json",
+      logger: Logger.new($stdout)
+    )
+      @api_key = api_key
+      ApiClient.api_cache_expiry = ApiClient.api_cache_expiry.merge(api_cache_expiry)
+      @api_cache_file = api_cache_file
+      @logger = logger
+      # Initialize our HTTP client
+      @http_cache = http_cache_file.nil? ? nil : FileCache.new(http_cache_file)
+      @http_client = Faraday.new do |builder|
+        # Indicate that the cache is not shared, meaning that private resources (depending on the session) can be cached as we consider only 1 user is using it for a given file cache.
+        # Use Marshal serializer as some URLs can't get decoded correctly due to UTF-8 issues
+        builder.use :http_cache,
+                    store: @http_cache,
+                    shared_cache: false,
+                    serializer: Marshal
+        builder.adapter Faraday.default_adapter
+      end
+      Cacheable.cache_adapter = :persistent_json
+      load_api_cache
+    end
+
+    # Send an HTTP request to the API and get back the answer as a JSON.
+    # Use caching.
+    #
+    # Parameters::
+    # * *path* (String): API path to contact (from v1/ and without .json)
+    # * *verb* (Symbol): Verb to be used (:get, :post...) [default: :get]
+    # Result::
+    # * Object: The JSON response
+    def api(path, verb: :get)
+      res = http(path, verb:)
+      json = JSON.parse(res.body)
+      uri = api_uri(path)
+      @logger.debug "[API call] - #{verb} #{uri} => #{res.status}\n#{
+          JSON.
+            pretty_generate(json).
+            split("\n").
+            map { |line| "  #{line}" }.
+            join("\n")
+        }\n#{
+          res.
+            headers.
+            map { |header, value| "  #{header}: #{value}" }.
+            join("\n")
+        }"
+      case res.status
+      when 200
+        # Happy
+      when 429
+        # Some limits of the API have been reached
+        raise LimitsExceededError, "Exceeding limits of API calls: #{res.headers.select { |header, _value| header =~ /^x-rl-.+$/ }}"
+      else
+        raise ApiError, "API #{uri} returned error code #{res.status}" unless res.status == '200'
+      end
+      json
+    end
+    cacheable_api(
+      :api,
+      expiry_from_key: proc do |key|
+        # Example of keys:
+        # NexusMods::ApiClient/api/games
+        # NexusMods::ApiClient/api/games/skyrimspecialedition/mods/2014
+        # NexusMods::ApiClient/api/games/skyrimspecialedition/mods/2014/files
+        # NexusMods::ApiClient/api/users/validate
+        key_components = key.split('/')[2..]
+        case key_components[0]
+        when 'games'
+          if key_components[1].nil?
+            ApiClient.api_cache_expiry[:games]
+          else
+            case key_components[2]
+            when 'mods'
+              case key_components[4]
+              when nil
+                ApiClient.api_cache_expiry[:mod]
+              when 'files'
+                ApiClient.api_cache_expiry[:mod_files]
+              else
+                raise "Unknown API path: #{key}"
+              end
+            else
+              raise "Unknown API path: #{key}"
+            end
+          end
+        when 'users'
+          # Don't cache this path as it is used to know API limits
+          0
+        else
+          raise "Unknown API path: #{key}"
+        end
+      end
+    )
+
+    # Send an HTTP request to the API and get back the HTTP response
+    #
+    # Parameters::
+    # * *path* (String): API path to contact (from v1/ and without .json)
+    # * *verb* (Symbol): Verb to be used (:get, :post...) [default: :get]
+    # Result::
+    # * Faraday::Response: The HTTP response
+    def http(path, verb: :get)
+      @http_client.send(verb) do |req|
+        req.url api_uri(path)
+        req.headers['apikey'] = @api_key
+        req.headers['User-Agent'] = "nexus_mods (#{RUBY_PLATFORM}) Ruby/#{RUBY_VERSION}"
+      end
+    end
+
+    # Load the API cache if a file was given to this client
+    def load_api_cache
+      Cacheable.cache_adapter.load(@api_cache_file) if @api_cache_file && File.exist?(@api_cache_file)
+    end
+
+    # Save the API cache if a file was given to this client
+    def save_api_cache
+      return unless @api_cache_file
+
+      FileUtils.mkdir_p(File.dirname(@api_cache_file))
+      Cacheable.cache_adapter.dump(@api_cache_file)
+    end
+
+    private
+
+    class << self
+
+      # Hash<Symbol,Integer>: Expiry time, per expiry key
+      attr_accessor :api_cache_expiry
+
+    end
+
+    # Default expiry times, in seconds
+    DEFAULT_API_CACHE_EXPIRY = {
+      games: 24 * 60 * 60,
+      mod: 24 * 60 * 60,
+      mod_files: 24 * 60 * 60
+    }
+
+    @api_cache_expiry = DEFAULT_API_CACHE_EXPIRY
+
+    # Get the real URI to query for a given API path
+    #
+    # Parameters::
+    # * *path* (String): API path to contact (from v1/ and without .json)
+    # Result::
+    # * String: The URI
+    def api_uri(path)
+      "https://api.nexusmods.com/v1/#{path}.json"
+    end
+
+  end
+
+end

data/lib/nexus_mods/cacheable_api.rb

@@ -0,0 +1,52 @@
+require 'cacheable'
+require 'nexus_mods/core_extensions/cacheable/method_generator'
+require 'nexus_mods/cacheable_with_expiry'
+
+class NexusMods
+
+  # Provide cacheable helpers for API methods that can be invalidated with an expiry time in seconds
+  module CacheableApi
+
+    # Callback when the module is included in another module/class
+    #
+    # Parameters::
+    # * *base* (Class or Module): The class/module including this module
+    def self.included(base)
+      base.include CacheableWithExpiry
+      base.extend CacheableApi::CacheableHelpers
+    end
+
+    # Some class helpers to make API calls easily cacheable
+    module CacheableHelpers
+
+      # Cache methods used for the NexusMods API with a given expiry time in seconds
+      #
+      # Parameters::
+      # * *original_method_names* (Array<Symbol>): List of methods to which this cache apply
+      # * *expiry_from_key* (Proc): Code giving the number of seconds of cache expiry from the key
+      #   * Parameters::
+      #     * *key* (String): The key for which we want the expiry time in seconds
+      #   * Result::
+      #     * Integer: Corresponding expiry time
+      def cacheable_api(*original_method_names, expiry_from_key:)
+        cacheable_with_expiry(
+          *original_method_names,
+          key_format: lambda do |target, method_name, method_args, method_kwargs|
+            (
+              [
+                target.class,
+                method_name
+              ] +
+                method_args +
+                method_kwargs.map { |key, value| "#{key}:#{value}" }
+            ).join('/')
+          end,
+          expiry_from_key:
+        )
+      end
+
+    end
+
+  end
+
+end

data/lib/nexus_mods/cacheable_with_expiry.rb

@@ -0,0 +1,70 @@
+require 'time'
+require 'nexus_mods/core_extensions/cacheable/cache_adapters/persistent_json_adapter'
+
+class NexusMods
+
+  # Add cacheable properties that can be expired using time in seconds
+  module CacheableWithExpiry
+
+    # Callback when the module is included in another module/class
+    #
+    # Parameters::
+    # * *base* (Class or Module): The class/module including this module
+    def self.included(base)
+      base.include Cacheable
+      base.extend CacheableWithExpiry::CacheableHelpers
+    end
+
+    # Some class helpers to make cacheable calls easy with expiry proc
+    module CacheableHelpers
+
+      # Wrap Cacheable's cacheable method to add the expiry_rules kwarg and use to invalidate the cache of a PersistentJsonAdapter based on the key format.
+      #
+      # Parameters::
+      # * *original_method_names* (Array<Symbol>): List of methods to which this cache apply
+      # * *opts* (Hash<Symbol,Object>): kwargs that will be transferred to the cacheable method, with the following ones interpreted:
+      #   * *expiry_from_key* (Proc): Code giving the number of seconds of cache expiry from the key
+      #     * Parameters::
+      #       * *key* (String): The key for which we want the expiry time in seconds
+      #     * Result::
+      #       * Integer: Corresponding expiry time
+      def cacheable_with_expiry(*original_method_names, **opts)
+        expiry_cache = {}
+        cacheable(
+          *original_method_names,
+          **opts.merge(
+            {
+              cache_options: {
+                expiry_from_key: opts[:expiry_from_key],
+                invalidate_if: proc do |key, options, context|
+                  next true unless context['invalidate_time']
+
+                  # Find if we know already the expiry for this key
+                  expiry_cache[key] = options[:expiry_from_key].call(key) unless expiry_cache.key?(key)
+                  expiry_cache[key].nil? || (Time.now.utc - Time.parse(context['invalidate_time']).utc > expiry_cache[key])
+                end,
+                update_context_after_fetch: proc do |_key, _value, _options, context|
+                  context['invalidate_time'] = Time.now.utc.strftime('%FT%TUTC')
+                end
+              }
+            }
+          )
+        )
+        @_cacheable_expiry_caches = [] unless defined?(@_cacheable_expiry_caches)
+        @_cacheable_expiry_caches << expiry_cache
+      end
+
+      # Clear expiry times caches
+      def clear_cacheable_expiry_caches
+        return unless defined?(@_cacheable_expiry_caches)
+
+        @_cacheable_expiry_caches.each do |expiry_cache|
+          expiry_cache.replace({})
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/nexus_mods/core_extensions/cacheable/cache_adapters/persistent_json_adapter.rb

@@ -0,0 +1,62 @@
+require 'cacheable'
+require 'json'
+
+module Cacheable
+
+  module CacheAdapters
+
+    # Adapter that adds JSON serialization functionality to save and load in files.
+    # Also adds contexts linked to keys being fetched to support more complex cache-invalidation schemes.
+    # This works only if:
+    # * The cached values are JSON serializable.
+    # * The cache keys are strings.
+    # * The context information is JSON serializable.
+    class PersistentJsonAdapter < MemoryAdapter
+
+      # Fetch a key with the givien cache options
+      #
+      # Parameters::
+      # * *key* (String): Key to be fetched
+      # * *options* (Hash): Cache options. The following options are interpreted by this fetch:
+      #   * *invalidate_if* (Proc): Code called to know if the cache should be invalidated for a given key:
+      #     * Parameters::
+      #       * *key* (String): The key for which we check the cache invalidation
+      #       * *options* (Hash): Cache options linked to this key
+      #       * *key_context* (Hash): Context linked to this key, that can be set using the update_context_after_fetch callback.
+      #     * Result::
+      #       * Boolean: Should we invalidate the cached value of this key?
+      #   * *update_context_after_fetch* (Proc): Code called when the value has been fetched for real (without cache), used to update the context
+      #     * Parameters::
+      #       * *key* (String): The key for which we just fetched the value
+      #       * *value* (Object): The value that has just been fetched
+      #       * *options* (Hash): Cache options linked to this key
+      #       * *key_context* (Hash): Context linked to this key, that is supposed to be updated in place by this callback
+      # * CodeBlock: Code called to fetch the value if not in the cache
+      # Result::
+      # * Object: The value for this key
+      def fetch(key, options = {})
+        context[key] = {} unless context.key?(key)
+        key_context = context[key]
+        delete(key) if options[:invalidate_if]&.call(key, options, key_context)
+        return read(key) if exist?(key)
+
+        value = yield
+        options[:update_context_after_fetch]&.call(key, value, options, key_context)
+        write(key, value)
+      end
+
+      # Clear the cache
+      def clear
+        @context = {}
+        super
+      end
+
+      private
+
+      attr_reader :context
+
+    end
+
+  end
+
+end

data/lib/nexus_mods/core_extensions/cacheable/method_generator.rb

@@ -0,0 +1,62 @@
+class NexusMods
+
+  module CoreExtensions
+
+    module Cacheable
+
+      # Make the cacheable method generators compatible with methods having kwargs
+      # TODO: Remove this core extension when cacheable will be compatible with kwargs
+      module MethodGenerator
+
+        private
+
+        # Create all methods to allow cacheable functionality, for a given original method name
+        #
+        # Parameters::
+        # * *original_method_name* (Symbol): The original method name
+        # * *opts* (Hash): The options given to the cacheable call
+        def create_cacheable_methods(original_method_name, opts = {})
+          method_names = create_method_names(original_method_name)
+          key_format_proc = opts[:key_format] || default_key_format
+
+          const_get(method_interceptor_module_name).class_eval do
+            define_method(method_names[:key_format_method_name]) do |*args, **kwargs|
+              key_format_proc.call(self, original_method_name, args, kwargs)
+            end
+
+            define_method(method_names[:clear_cache_method_name]) do |*args, **kwargs|
+              ::Cacheable.cache_adapter.delete(__send__(method_names[:key_format_method_name], *args, **kwargs))
+            end
+
+            define_method(method_names[:without_cache_method_name]) do |*args, **kwargs|
+              original_method = method(original_method_name).super_method
+              original_method.call(*args, **kwargs)
+            end
+
+            define_method(method_names[:with_cache_method_name]) do |*args, **kwargs|
+              ::Cacheable.cache_adapter.fetch(__send__(method_names[:key_format_method_name], *args, **kwargs), opts[:cache_options]) do
+                __send__(method_names[:without_cache_method_name], *args, **kwargs)
+              end
+            end
+
+            define_method(original_method_name) do |*args, **kwargs|
+              unless_proc = opts[:unless].is_a?(Symbol) ? opts[:unless].to_proc : opts[:unless]
+
+              if unless_proc&.call(self, original_method_name, args)
+                __send__(method_names[:without_cache_method_name], *args, **kwargs)
+              else
+                __send__(method_names[:with_cache_method_name], *args, **kwargs)
+              end
+            end
+          end
+        end
+
+      end
+
+    end
+
+  end
+
+end
+
+Cacheable::MethodGenerator.prepend NexusMods::CoreExtensions::Cacheable::MethodGenerator

data/lib/nexus_mods/file_cache.rb

@@ -0,0 +1,71 @@
+class NexusMods
+
+  # Simple key/value file cache
+  class FileCache
+
+    # Constructor
+    #
+    # Parameters::
+    # * *file* (String): File to use as a cache
+    def initialize(file)
+      @file = file
+      @cache_content = File.exist?(file) ? JSON.parse(File.read(file)) : {}
+    end
+
+    # Dump the cache in file
+    def dump
+      File.write(@file, @cache_content.to_json)
+    end
+
+    # Get the cache content as a Hash
+    #
+    # Result::
+    # * Hash<String, Object>: Cache content
+    def to_h
+      @cache_content
+    end
+
+    # Is a given key present in the cache?
+    #
+    # Parameters::
+    # * *key* (String): The key
+    # Result::
+    # * Boolean: Is a given key present in the cache?
+    def key?(key)
+      @cache_content.key?(key)
+    end
+
+    # Read a key from the cache
+    #
+    # Parameters:
+    # * *key* (String): The cache key
+    # Result::
+    # * Object or nil: JSON-serializable object storing the value, or nil in case of cache-miss
+    def read(key)
+      @cache_content.key?(key) ? @cache_content[key] : nil
+    end
+
+    alias [] read
+
+    # Write a key/value in the cache
+    #
+    # Parameters:
+    # * *key* (String): The key
+    # * *value* (Object): JSON-serializable object storing the value
+    def write(key, value)
+      @cache_content[key] = value
+    end
+
+    alias []= write
+
+    # Delete a key in the cache
+    #
+    # Parameters:
+    # * *key* (String): The key
+    def delete(key)
+      @cache_content.delete(key)
+    end
+
+  end
+
+end

data/lib/nexus_mods/version.rb

@@ -1,5 +1,5 @@
 class NexusMods
 
-  VERSION = '0.1.1'
+  VERSION = '0.3.0'
 
 end