nexus_mods 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efdb25aee2a65f563017933ab77b1360d3ab04d26abf3f945cd9c1cf3d0a1a0d
-  data.tar.gz: dc538a350901669fbca2e6cbc299daf091bcf0779f82c3e9b718398b5f61e877
+  metadata.gz: 79e4d81970dd1549db43105a2a155b6b275692df4f06827e2234ab02fce6276b
+  data.tar.gz: 4d96df8a39784c8a2eb6fb9bd72a247f3cafa2765aa03059dfc661afd9db7a38
 SHA512:
-  metadata.gz: 6e2f2ee9025ab0650fc96ad4d10ff41e8375caa8c6ab51e64ceec5527630e97806bfdbce74d2db2ba63bc58a45371392c98d4fb20ccbd7399b2711123fce125f
-  data.tar.gz: a6519240cb31bc1cf25a5f0b7001be67e91b41588817739f50a8c8b4d1558a2129ecb43ba6239454717fe47d6aea47f152eeb08c374bce18c83fe84003a378fd
+  metadata.gz: 9c13d188694e09dc06998846791322a4887bbb5163ff634d5e6f813abca187a6a2dc8aeb102e040b43812d6276feb6c1ee59665c5e5e408c6acbff4dca0539b3
+  data.tar.gz: 3e37eb153f00bb6335efb8e0b377065f4b0613cbef46066a1a5d7095b1e1767b1786d59f28681298e75be49e1cfeb739ea6ce2f7b13fefc6b28362b27d7536b5

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [v0.4.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v0.3.0...v0.4.0) (2023-04-10 10:15:41)
+
+### Features
+
+* [[Feature] Add persistent API caching in files](https://github.com/Muriel-Salvan/nexus_mods/commit/f124ecf58b0f478ecdca5f6ad2309779d1ab67ac)
+
+# [v0.3.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v0.2.0...v0.3.0) (2023-04-10 09:13:43)
+
+### Features
+
+* [[Feature] Implement caching of API queries with configurable expiry times](https://github.com/Muriel-Salvan/nexus_mods/commit/7f74e25d046adbcec394ce33a3802ed9e91f3a52)
+
 # [v0.2.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v0.1.1...v0.2.0) (2023-04-10 08:45:44)
 
 ### Features

data/lib/nexus_mods/api_client.rb

@@ -0,0 +1,189 @@
+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
+
+    # Default expiry times, in seconds
+    DEFAULT_API_CACHE_EXPIRY = {
+      games: 24 * 60 * 60,
+      mod: 24 * 60 * 60,
+      mod_files: 24 * 60 * 60
+    }
+
+    # 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
+      @api_cache_expiry = DEFAULT_API_CACHE_EXPIRY.merge(api_cache_expiry)
+      @api_cache_file = api_cache_file
+      ApiClient.api_client = self
+      @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_client.api_cache_expiry[:games]
+          else
+            case key_components[2]
+            when 'mods'
+              case key_components[4]
+              when nil
+                ApiClient.api_client.api_cache_expiry[:mod]
+              when 'files'
+                ApiClient.api_client.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,
+      on_cache_update: proc do
+        ApiClient.api_client.save_api_cache
+      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.save(@api_cache_file)
+    end
+
+    # Some attributes exposed for the cacheable feature to work
+    attr_reader :api_cache_expiry
+
+    private
+
+    class << self
+
+      # ApiClient: The API client to be used by the cacheable adapter (singleton pattern)
+      attr_accessor :api_client
+
+    end
+
+    @api_client = nil
+
+    # 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,58 @@
+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
+      # * *on_cache_update* (Proc): Proc called when the cache has been updated
+      def cacheable_api(*original_method_names, expiry_from_key:, on_cache_update:)
+        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:,
+          cache_options: {
+            on_cache_update: proc do |_adapter, _key, _value, _options, _context|
+              on_cache_update.call
+            end
+          }
+        )
+      end
+
+    end
+
+  end
+
+end

data/lib/nexus_mods/cacheable_with_expiry.rb

@@ -0,0 +1,72 @@
+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: (opts[:cache_options] || {}).merge(
+                {
+                  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,98 @@
+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 or nil): Optional 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 or nil): Optional 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
+      #   * *on_cache_update* (Proc or nil): Optional code called once the cache has been updated
+      #     * Parameters::
+      #       * *adapter* (Object): Adapter that has the cache being updated
+      #       * *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
+      # * 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)
+        options[:on_cache_update]&.call(self, key, value, options, key_context)
+        value
+      end
+
+      # Clear the cache
+      def clear
+        @context = {}
+        super
+      end
+
+      # Save the cache and context into a JSON file
+      #
+      # Parameters::
+      # * *file* (String): The file to save to
+      def save(file)
+        # Remove from the context the keys that are not in the cache
+        File.write(
+          file,
+          JSON.dump(
+            {
+              'cache' => cache,
+              'context' => context.select { |key, _value| @cache.key?(key) }
+            }
+          )
+        )
+      end
+
+      # Load the cache and context from a JSON file
+      #
+      # Parameters::
+      # * *file* (String): The file to load from
+      def load(file)
+        loaded_content = JSON.parse(File.read(file))
+        @cache = loaded_content['cache']
+        @context = loaded_content['context']
+      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.2.0'
+  VERSION = '0.4.0'
 
 end

data/lib/nexus_mods.rb

@@ -1,8 +1,7 @@
-require 'addressable/uri'
 require 'json'
 require 'time'
 require 'tmpdir'
-require 'faraday'
+require 'nexus_mods/api_client'
 require 'nexus_mods/api/api_limits'
 require 'nexus_mods/api/category'
 require 'nexus_mods/api/game'
@@ -40,27 +39,39 @@ class NexusMods
   # * *game_domain_name* (String): Game domain name to query by default [default: 'skyrimspecialedition']
   # * *mod_id* (Integer): Mod to query by default [default: 1]
   # * *file_id* (Integer): File to query by default [default: 1]
+  # * *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,
     game_domain_name: 'skyrimspecialedition',
     mod_id: 1,
     file_id: 1,
+    http_cache_file: "#{Dir.tmpdir}/nexus_mods_http_cache.json",
+    api_cache_expiry: {},
+    api_cache_file: "#{Dir.tmpdir}/nexus_mods_api_cache.json",
     logger: Logger.new($stdout)
   )
-    @api_key = api_key
     @game_domain_name = game_domain_name
     @mod_id = mod_id
     @file_id = file_id
     @logger = logger
     @premium = false
-    # Initialize our HTTP client
-    @http_client = Faraday.new do |builder|
-      builder.adapter Faraday.default_adapter
-    end
+    @api_client = ApiClient.new(
+      api_key:,
+      http_cache_file:,
+      api_cache_expiry:,
+      api_cache_file:,
+      logger:
+    )
+
     # Check that the key is correct and know if the user is premium
     begin
-      @premium = api('users/validate')['is_premium?']
+      @premium = @api_client.api('users/validate')['is_premium?']
     rescue LimitsExceededError
       raise
     rescue ApiError
@@ -74,7 +85,7 @@ class NexusMods
   # Result::
   # * ApiLimits: API calls limits
   def api_limits
-    api_limits_headers = http('users/validate').headers
+    api_limits_headers = @api_client.http('users/validate').headers
     Api::ApiLimits.new(
       daily_limit: Integer(api_limits_headers['x-rl-daily-limit']),
       daily_remaining: Integer(api_limits_headers['x-rl-daily-remaining']),
@@ -90,7 +101,7 @@ class NexusMods
   # Result::
   # * Array<Game>: List of games
   def games
-    api('games').map do |game_json|
+    @api_client.api('games').map do |game_json|
       # First create categories tree
       # Hash<Integer, [Category, Integer]>: Category and its parent category id, per category id
       categories = game_json['categories'].to_h do |category_json|
@@ -137,7 +148,7 @@ class NexusMods
   # Result::
   # * Mod: Mod information
   def mod(game_domain_name: @game_domain_name, mod_id: @mod_id)
-    mod_json = api "games/#{game_domain_name}/mods/#{mod_id}"
+    mod_json = @api_client.api "games/#{game_domain_name}/mods/#{mod_id}"
     Api::Mod.new(
       uid: mod_json['uid'],
       mod_id: mod_json['mod_id'],
@@ -185,7 +196,7 @@ class NexusMods
   # Result::
   # * Array<ModFile>: List of mod's files
   def mod_files(game_domain_name: @game_domain_name, mod_id: @mod_id)
-    api("games/#{game_domain_name}/mods/#{mod_id}/files")['files'].map do |file_json|
+    @api_client.api("games/#{game_domain_name}/mods/#{mod_id}/files")['files'].map do |file_json|
       category_id = FILE_CATEGORIES[file_json['category_id']]
       raise "Unknown file category: #{file_json['category_id']}" if category_id.nil?
 
@@ -210,66 +221,4 @@ class NexusMods
     end
   end
 
-  private
-
-  # Send an HTTP request to the API and get back the answer as a JSON
-  #
-  # 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
-
-  # 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
-
-  # 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

data/spec/nexus_mods_test/helpers.rb

@@ -55,6 +55,9 @@ module NexusModsTest
     def nexus_mods(**args)
       if @nexus_mods.nil?
         args[:api_key] = MOCKED_API_KEY unless args.key?(:api_key)
+        # By default running tests should not persistent cache files
+        args[:http_cache_file] = nil unless args.key?(:http_cache_file)
+        args[:api_cache_file] = nil unless args.key?(:api_cache_file)
         # Redirect any log into a string so that they don't pollute the tests output and they could be asserted.
         nexus_mods_logger = StringIO.new
         args[:logger] = Logger.new(nexus_mods_logger)
@@ -134,6 +137,19 @@ module NexusModsTest
       )
     end
 
+    # Setup an API cache file to be used (does not create it)
+    #
+    # Parameters::
+    # * CodeBlock: The code called when the API cache file is reserved
+    #   * Parameters::
+    #     * *api_cache_file* (String): File name to be used for the API cache file
+    def with_api_cache_file
+      api_cache_file = "#{Dir.tmpdir}/nexus_mods_test/api_cache.json"
+      FileUtils.mkdir_p(File.dirname(api_cache_file))
+      FileUtils.rm_f(api_cache_file)
+      yield api_cache_file
+    end
+
   end
 
 end
@@ -145,6 +161,8 @@ RSpec.configure do |config|
   config.include NexusModsTest::Factories::ModFiles
   config.before do
     @nexus_mods = nil
+    # Reload the ApiClient as it stores caches at class level
+    NexusMods::ApiClient.clear_cacheable_expiry_caches
     # Keep a list of the etags we should have returned, so that we know when queries should contain them
     # Array<String>
     @expected_returned_etags = []
@@ -152,6 +170,11 @@ RSpec.configure do |config|
     # Array< [ WebMock::RequestStub, Integer ] >
     @expected_stubs = []
   end
+  config.after do
+    @expected_stubs.each do |(stub, times)|
+      expect(stub).to have_been_made.times(times)
+    end
+  end
 end
 
 # Set a bigger output length for expectation errors, as most error messages include API keys and headers which can be lengthy

data/spec/nexus_mods_test/scenarios/nexus_mods_caching_spec.rb

@@ -0,0 +1,157 @@
+require 'fileutils'
+
+describe NexusMods do
+
+  context 'when testing caching' do
+
+    it 'does not cache user queries' do
+      expect_validate_user(times: 3)
+      nexus_mods.api_limits
+      nexus_mods.api_limits
+    end
+
+    it 'caches games queries' do
+      expect_validate_user
+      expect_http_call_to(
+        path: '/v1/games.json',
+        json: [
+          json_game100,
+          json_game101
+        ]
+      )
+      games = nexus_mods.games
+      expect(nexus_mods.games).to eq(games)
+    end
+
+    it 'caches mod queries' do
+      expect_validate_user
+      expect_http_call_to(
+        path: '/v1/games/skyrimspecialedition/mods/2014.json',
+        json: json_complete_mod
+      )
+      mod = nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+      expect(nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(mod)
+    end
+
+    it 'caches mod files queries' do
+      expect_validate_user
+      expect_http_call_to(
+        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
+        json: { files: [json_mod_file2472, json_mod_file2487] }
+      )
+      mod_files = nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+      expect(nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(mod_files)
+    end
+
+    it 'expires games queries cache' do
+      expect_validate_user
+      expect_http_call_to(
+        path: '/v1/games.json',
+        json: [
+          json_game100,
+          json_game101
+        ],
+        times: 2
+      )
+      nexus_mods_instance = nexus_mods(api_cache_expiry: { games: 1 })
+      games = nexus_mods_instance.games
+      sleep 2
+      expect(nexus_mods_instance.games).to eq(games)
+    end
+
+    it 'expires mod queries cache' do
+      expect_validate_user
+      expect_http_call_to(
+        path: '/v1/games/skyrimspecialedition/mods/2014.json',
+        json: json_complete_mod,
+        times: 2
+      )
+      nexus_mods_instance = nexus_mods(api_cache_expiry: { mod: 1 })
+      mod = nexus_mods_instance.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+      sleep 2
+      expect(nexus_mods_instance.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(mod)
+    end
+
+    it 'expires mod files queries cache' do
+      expect_validate_user
+      expect_http_call_to(
+        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
+        json: { files: [json_mod_file2472, json_mod_file2487] },
+        times: 2
+      )
+      nexus_mods_instance = nexus_mods(api_cache_expiry: { mod_files: 1 })
+      mod_files = nexus_mods_instance.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+      sleep 2
+      expect(nexus_mods_instance.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(mod_files)
+    end
+
+    context 'with file persistence' do
+
+      it 'persists API cache in a file' do
+        with_api_cache_file do |api_cache_file|
+          expect_validate_user
+          expect_http_call_to(
+            path: '/v1/games.json',
+            json: [
+              json_game100,
+              json_game101
+            ]
+          )
+          nexus_mods(api_cache_file:).games
+          expect(File.exist?(api_cache_file)).to be true
+          expect(File.size(api_cache_file)).to be > 0
+        end
+      end
+
+      it 'uses API cache from a file' do
+        with_api_cache_file do |api_cache_file|
+          expect_validate_user(times: 2)
+          expect_http_call_to(
+            path: '/v1/games.json',
+            json: [
+              json_game100,
+              json_game101
+            ]
+          )
+          # Generate the cache first
+          games = nexus_mods(api_cache_file:).games
+          # Force a new instance of NexusMods API to run
+          @nexus_mods = nil
+          expect(nexus_mods(api_cache_file:).games).to eq games
+        end
+      end
+
+      it 'completes the API cache from a file' do
+        with_api_cache_file do |api_cache_file|
+          expect_validate_user(times: 3)
+          # Generate the cache first for games only
+          expect_http_call_to(
+            path: '/v1/games.json',
+            json: [
+              json_game100,
+              json_game101
+            ]
+          )
+          games = nexus_mods(api_cache_file:).games
+          # Force a new instance of NexusMods API to run
+          @nexus_mods = nil
+          # Complete the cache with a mod
+          expect_http_call_to(
+            path: '/v1/games/skyrimspecialedition/mods/2014.json',
+            json: json_complete_mod
+          )
+          mod = nexus_mods(api_cache_file:).mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+          # Force a new instance of NexusMods API to run
+          @nexus_mods = nil
+          # Check that both API calls were cached correctly
+          nexus_mods_instance = nexus_mods(api_cache_file:)
+          expect(nexus_mods_instance.games).to eq games
+          expect(nexus_mods_instance.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq mod
+        end
+      end
+
+    end
+
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexus_mods
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Muriel Salvan
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: cacheable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -128,6 +142,12 @@ files:
 - lib/nexus_mods/api/mod.rb
 - lib/nexus_mods/api/mod_file.rb
 - lib/nexus_mods/api/user.rb
+- lib/nexus_mods/api_client.rb
+- lib/nexus_mods/cacheable_api.rb
+- lib/nexus_mods/cacheable_with_expiry.rb
+- lib/nexus_mods/core_extensions/cacheable/cache_adapters/persistent_json_adapter.rb
+- lib/nexus_mods/core_extensions/cacheable/method_generator.rb
+- lib/nexus_mods/file_cache.rb
 - lib/nexus_mods/version.rb
 - spec/nexus_mods_test/factories/games.rb
 - spec/nexus_mods_test/factories/mod_files.rb
@@ -138,6 +158,7 @@ files:
 - spec/nexus_mods_test/scenarios/nexus_mods/api/mod_file_spec.rb
 - spec/nexus_mods_test/scenarios/nexus_mods/api/mod_spec.rb
 - spec/nexus_mods_test/scenarios/nexus_mods_access_spec.rb
+- spec/nexus_mods_test/scenarios/nexus_mods_caching_spec.rb
 - spec/nexus_mods_test/scenarios/rubocop_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/Muriel-Salvan/nexus_mods