nexus_mods 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79e4d81970dd1549db43105a2a155b6b275692df4f06827e2234ab02fce6276b
-  data.tar.gz: 4d96df8a39784c8a2eb6fb9bd72a247f3cafa2765aa03059dfc661afd9db7a38
+  metadata.gz: 758229de2b795e860d8b150e4bbc8a2d516f6e49c2773ac242c0b67472f6c157
+  data.tar.gz: 96e38216e7f54b9198c9362bb01b7ea0fdde2205e357a419123b3337c2791ee4
 SHA512:
-  metadata.gz: 9c13d188694e09dc06998846791322a4887bbb5163ff634d5e6f813abca187a6a2dc8aeb102e040b43812d6276feb6c1ee59665c5e5e408c6acbff4dca0539b3
-  data.tar.gz: 3e37eb153f00bb6335efb8e0b377065f4b0613cbef46066a1a5d7095b1e1767b1786d59f28681298e75be49e1cfeb739ea6ce2f7b13fefc6b28362b27d7536b5
+  metadata.gz: 8c2fa3106f59e59472bcb39d107d28bba9ce394e9c7d2783d5b60e0074ea7070bfd175aaa1dd543397b057aaabd7bd0778f299609acbf30a706870f4460c95ab
+  data.tar.gz: f2f6994f254288a5c8b7ba806a3f0b9b18a044aacdf9b7edd381b629a6e97c9d49f881ba566437beb4739cf32a2a0b11575fd71f574210e62763fb5fcc86b8cb

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# [v0.5.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v0.4.0...v0.5.0) (2023-04-10 17:05:11)
+
+### Features
+
+* [[Feature] Add clear_cache parameters to invalidate the API cache at will](https://github.com/Muriel-Salvan/nexus_mods/commit/44958e35eae20ef818e3d4735cc3bd3008cfc5df)
+
 # [v0.4.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v0.3.0...v0.4.0) (2023-04-10 10:15:41)
 
 ### Features

data/lib/nexus_mods/api_client.rb

@@ -63,9 +63,65 @@ class NexusMods
     # Parameters::
     # * *path* (String): API path to contact (from v1/ and without .json)
     # * *verb* (Symbol): Verb to be used (:get, :post...) [default: :get]
+    # * *clear_cache* (Boolean): Should we clear the API cache for this resource? [default: false]
     # Result::
     # * Object: The JSON response
-    def api(path, verb: :get)
+    def api(path, verb: :get, clear_cache: false)
+      clear_cached_api_cache(path, verb:) if clear_cache
+      cached_api(path, verb:)
+    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
+
+    # 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 cached_api(path, verb: :get)
       res = http(path, verb:)
       json = JSON.parse(res.body)
       uri = api_uri(path)
@@ -93,14 +149,14 @@ class NexusMods
       json
     end
     cacheable_api(
-      :api,
+      :cached_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..]
+        # NexusMods::ApiClient/cached_api/games/verb:get
+        # NexusMods::ApiClient/cached_api/games/skyrimspecialedition/mods/2014/verb:get
+        # NexusMods::ApiClient/cached_api/games/skyrimspecialedition/mods/2014/files/verb:get
+        # NexusMods::ApiClient/cached_api/users/validate/verb:get
+        key_components = key.split('/')[2..-2]
         case key_components[0]
         when 'games'
           if key_components[1].nil?
@@ -132,48 +188,6 @@ class NexusMods
       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::

data/lib/nexus_mods/version.rb

@@ -1,5 +1,5 @@
 class NexusMods
 
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 
 end

data/lib/nexus_mods.rb

@@ -98,10 +98,12 @@ class NexusMods
 
   # Get the list of games
   #
+  # Parameters::
+  # * *clear_cache* (Boolean): Should we clear the API cache for this resource? [default: false]
   # Result::
   # * Array<Game>: List of games
-  def games
-    @api_client.api('games').map do |game_json|
+  def games(clear_cache: false)
+    @api_client.api('games', clear_cache:).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|
@@ -145,10 +147,11 @@ class NexusMods
   # Parameters::
   # * *game_domain_name* (String): Game domain name to query by default [default: @game_domain_name]
   # * *mod_id* (Integer): The mod ID [default: @mod_id]
+  # * *clear_cache* (Boolean): Should we clear the API cache for this resource? [default: false]
   # Result::
   # * Mod: Mod information
-  def mod(game_domain_name: @game_domain_name, mod_id: @mod_id)
-    mod_json = @api_client.api "games/#{game_domain_name}/mods/#{mod_id}"
+  def mod(game_domain_name: @game_domain_name, mod_id: @mod_id, clear_cache: false)
+    mod_json = @api_client.api("games/#{game_domain_name}/mods/#{mod_id}", clear_cache:)
     Api::Mod.new(
       uid: mod_json['uid'],
       mod_id: mod_json['mod_id'],
@@ -193,10 +196,11 @@ class NexusMods
   # Parameters::
   # * *game_domain_name* (String): Game domain name to query by default [default: @game_domain_name]
   # * *mod_id* (Integer): The mod ID [default: @mod_id]
+  # * *clear_cache* (Boolean): Should we clear the API cache for this resource? [default: false]
   # Result::
   # * Array<ModFile>: List of mod's files
-  def mod_files(game_domain_name: @game_domain_name, mod_id: @mod_id)
-    @api_client.api("games/#{game_domain_name}/mods/#{mod_id}/files")['files'].map do |file_json|
+  def mod_files(game_domain_name: @game_domain_name, mod_id: @mod_id, clear_cache: false)
+    @api_client.api("games/#{game_domain_name}/mods/#{mod_id}/files", clear_cache:)['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?
 
@@ -221,4 +225,9 @@ class NexusMods
     end
   end
 
+  # TODO: Check http cache usefulness and either test it or remove it
+  # TODO: Check if attr_reader of mod_id and game_id is needed and remove it if not
+  # TODO: Find better cache keys
+  # TODO: Documentation and examples
+
 end

data/spec/nexus_mods_test/helpers.rb

@@ -59,13 +59,24 @@ module NexusModsTest
         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)
+        @nexus_mods_logger = StringIO.new
+        args[:logger] = Logger.new(@nexus_mods_logger)
         @nexus_mods = NexusMods.new(**args)
       end
       @nexus_mods
     end
 
+    # Reset the NexusMods instance.
+    # Dump the output if needed for debugging purposes.
+    def reset_nexus_mods
+      if @nexus_mods && test_debug?
+        puts '===== NexusMods output BEGIN ====='
+        puts @nexus_mods_logger.string
+        puts '===== NexusMods output END ====='
+      end
+      @nexus_mods = nil
+    end
+
     # Expect an HTTP API call to be made, and mock the corresponding HTTP response.
     # Handle the API key and user agent.
     #
@@ -150,6 +161,14 @@ module NexusModsTest
       yield api_cache_file
     end
 
+    # Are we in test debug mode?
+    #
+    # Result::
+    # * Boolean: Are we in test debug mode?
+    def test_debug?
+      ENV['TEST_DEBUG'] == '1'
+    end
+
   end
 
 end
@@ -175,6 +194,11 @@ RSpec.configure do |config|
       expect(stub).to have_been_made.times(times)
     end
   end
+  config.around do |example|
+    example.call
+  ensure
+    reset_nexus_mods
+  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

@@ -23,6 +23,20 @@ describe NexusMods do
       expect(nexus_mods.games).to eq(games)
     end
 
+    it 'does not cache games queries if asked' do
+      expect_validate_user
+      expect_http_call_to(
+        path: '/v1/games.json',
+        json: [
+          json_game100,
+          json_game101
+        ],
+        times: 2
+      )
+      games = nexus_mods.games
+      expect(nexus_mods.games(clear_cache: true)).to eq(games)
+    end
+
     it 'caches mod queries' do
       expect_validate_user
       expect_http_call_to(
@@ -33,6 +47,17 @@ describe NexusMods do
       expect(nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(mod)
     end
 
+    it 'does not cache mod queries if asked' do
+      expect_validate_user
+      expect_http_call_to(
+        path: '/v1/games/skyrimspecialedition/mods/2014.json',
+        json: json_complete_mod,
+        times: 2
+      )
+      mod = nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+      expect(nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014, clear_cache: true)).to eq(mod)
+    end
+
     it 'caches mod files queries' do
       expect_validate_user
       expect_http_call_to(
@@ -43,6 +68,17 @@ describe NexusMods do
       expect(nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(mod_files)
     end
 
+    it 'does not cache mod files queries if asked' 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
+      )
+      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, clear_cache: true)).to eq(mod_files)
+    end
+
     it 'expires games queries cache' do
       expect_validate_user
       expect_http_call_to(
@@ -85,6 +121,25 @@ describe NexusMods do
       expect(nexus_mods_instance.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(mod_files)
     end
 
+    it 'only clears the cache of the wanted resource' do
+      expect_validate_user
+      expect_http_call_to(
+        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
+        json: { files: [json_mod_file2472] },
+        times: 2
+      )
+      expect_http_call_to(
+        path: '/v1/games/skyrimspecialedition/mods/2015/files.json',
+        json: { files: [json_mod_file2487] }
+      )
+      mod_files20141 = nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+      mod_files20151 = nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2015)
+      mod_files20142 = nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014, clear_cache: true)
+      mod_files20152 = nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2015)
+      expect(mod_files20141).to eq(mod_files20142)
+      expect(mod_files20151).to eq(mod_files20152)
+    end
+
     context 'with file persistence' do
 
       it 'persists API cache in a file' do
@@ -116,11 +171,54 @@ describe NexusMods do
           # Generate the cache first
           games = nexus_mods(api_cache_file:).games
           # Force a new instance of NexusMods API to run
-          @nexus_mods = nil
+          reset_nexus_mods
           expect(nexus_mods(api_cache_file:).games).to eq games
         end
       end
 
+      it 'uses API cache from a file, taking expiry time into account' 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
+            ],
+            times: 2
+          )
+          # Generate the cache first
+          games = nexus_mods(api_cache_file:, api_cache_expiry: { games: 1 }).games
+          # Force a new instance of NexusMods API to run
+          reset_nexus_mods
+          sleep 2
+          # As the expiry time is 1 second, then the cache should still be invalidated
+          expect(nexus_mods(api_cache_file:, api_cache_expiry: { games: 1 }).games).to eq games
+        end
+      end
+
+      it 'uses API cache from a file, taking expiry time of the new process into account' 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
+            ],
+            times: 2
+          )
+          # Generate the cache first
+          games = nexus_mods(api_cache_file:, api_cache_expiry: { games: 10 }).games
+          # Force a new instance of NexusMods API to run
+          reset_nexus_mods
+          sleep 2
+          # Even if the expiry time was 10 seconds while fetching the resource,
+          # if we decide it has to be 1 second now then it has to be invalidated.
+          expect(nexus_mods(api_cache_file:, api_cache_expiry: { games: 1 }).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)
@@ -134,7 +232,7 @@ describe NexusMods do
           )
           games = nexus_mods(api_cache_file:).games
           # Force a new instance of NexusMods API to run
-          @nexus_mods = nil
+          reset_nexus_mods
           # Complete the cache with a mod
           expect_http_call_to(
             path: '/v1/games/skyrimspecialedition/mods/2014.json',
@@ -142,7 +240,7 @@ describe NexusMods do
           )
           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
+          reset_nexus_mods
           # Check that both API calls were cached correctly
           nexus_mods_instance = nexus_mods(api_cache_file:)
           expect(nexus_mods_instance.games).to eq games
@@ -150,6 +248,41 @@ describe NexusMods do
         end
       end
 
+      it 'clears the cache of a wanted resource in the API cache file as well' do
+        with_api_cache_file do |api_cache_file|
+          expect_validate_user(times: 3)
+          # Generate the cache first for 2 mod files queries
+          expect_http_call_to(
+            path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
+            json: { files: [json_mod_file2472] },
+            times: 2
+          )
+          expect_http_call_to(
+            path: '/v1/games/skyrimspecialedition/mods/2015/files.json',
+            json: { files: [json_mod_file2487] }
+          )
+          nexus_mods_instance1 = nexus_mods(api_cache_file:)
+          mod_files20141 = nexus_mods_instance1.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+          mod_files20151 = nexus_mods_instance1.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2015)
+          # Force a new instance of NexusMods API to run
+          reset_nexus_mods
+          # Clear the cache of the first API query
+          nexus_mods_instance2 = nexus_mods(api_cache_file:)
+          mod_files20142 = nexus_mods_instance2.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014, clear_cache: true)
+          mod_files20152 = nexus_mods_instance2.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2015)
+          # Force a new instance of NexusMods API to run
+          reset_nexus_mods
+          # Get again the data, it should have been in the cache already
+          nexus_mods_instance3 = nexus_mods(api_cache_file:)
+          mod_files20143 = nexus_mods_instance3.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+          mod_files20153 = nexus_mods_instance3.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2015)
+          expect(mod_files20141).to eq(mod_files20142)
+          expect(mod_files20141).to eq(mod_files20143)
+          expect(mod_files20151).to eq(mod_files20152)
+          expect(mod_files20151).to eq(mod_files20153)
+        end
+      end
+
     end
 
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexus_mods
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Muriel Salvan