factorix 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0313b61d47124abdc416a512ef8027e0885e26aed91202c422349e43d9ec667
-  data.tar.gz: 00ce104d88ff8a4a5c1e5ea54afbba614775bf93e1c808c95549b458974883f3
+  metadata.gz: f1d6b99d769a238f64676cfd19aef4d0f8852d2dc38df210eb753a8bc202f67f
+  data.tar.gz: c51b472d2eb47e7d0d39c4789112da30faf5fbf7e225da330d19e989bce86f43
 SHA512:
-  metadata.gz: 7dcd0c9873615cb03f613f7298c535ad4bf2ceb9bdd640b4fcfee3b2cfd31860bc62daaa60568a07149c3ae8a806112bcfc369179e18457bf16c0307f5bc89db
-  data.tar.gz: 29a513f560d14e1b8bc1fa07e1de2378685de195ae97c79b4993f762af33e245da381c6554eee739494425fa59beb2755a15a2734b917473c9f4baf247171500
+  metadata.gz: 0e9bf68578d26f4b08e77028b1da59ff8d972f807822be5fa19ca1eb951e89412a3314a3db5fde1fcd821f399ee6c9e4e8c28e37d2d0c5e3d000046c5e663d2f
+  data.tar.gz: 81222393a0ab0a6b6e2cbbccac52dec243d4806ef688a1240a01367142094e368175caba564d4842ebd627ebdef98e322f8217b14a3424e8e20c7bbeddc248a4

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 ## [Unreleased]
 
+## [0.7.0] - 2026-01-24
+
+### Added
+
+- Add pluggable cache backend architecture with Redis and S3 support (#18, #19)
+  - Configure backend per cache type: `config.cache.<type>.backend = :file_system | :redis | :s3`
+  - **Redis backend** (`Cache::Redis`): requires `redis` gem (~> 5)
+    - Distributed locking via Lua script for atomic lock release
+    - Auto-namespaced keys: `factorix-cache:{cache_type}:{key}`
+  - **S3 backend** (`Cache::S3`): requires `aws-sdk-s3` gem
+    - Distributed locking via conditional PUT (`if_none_match: "*"`)
+    - TTL managed via S3 custom metadata, age from native `Last-Modified`
+  - `cache stat` command displays backend-specific information (directory, URL, bucket, etc.)
+
+### Changed
+
+- Refactor `Cache::FileSystem` to use `cache_type:` parameter instead of `root:` (#25)
+  - Aligns interface with other backends for consistent initialization
+  - Cache directory is now auto-computed from `Container[:runtime].factorix_cache_dir / cache_type`
+
+### Removed
+
+- Remove deprecated `Factorix::Application` compatibility class
+  - Use `Factorix::Container` for DI (`[]`, `resolve`, `register`)
+  - Use `Factorix.config` and `Factorix.configure` for configuration
+
+## [0.6.0] - 2026-01-18
+
+### Changed
+
+- Reorganize configuration and DI container interfaces (#7, #9)
+  - `Factorix::Application` renamed to `Factorix::Container` (DI container only)
+  - Configuration interface (`config`, `configure`, `load_config`) moved to `Factorix` module
+  - Use `Factorix.configure { |c| ... }` instead of `Factorix::Container.configure { |c| ... }`
+
+### Fixed
+
+- Fix integer CLI options being parsed as strings after dry-cli 1.4.0 update (#12)
+
+### Deprecated
+
+- `Factorix::Application` still works but emits deprecation warnings; will be removed in v1.0
+  - DI methods (`[]`, `resolve`, `register`) delegate to `Factorix::Container`
+  - Configuration methods (`config`, `configure`) delegate to `Factorix`
+
 ## [0.5.1] - 2026-01-13
 
 ### Fixed

data/README.md

@@ -65,7 +65,7 @@ $EDITOR ~/.config/factorix/config.rb
 
 **Example configuration:**
 ```ruby
-Factorix::Application.configure do |config|
+Factorix.configure do |config|
   config.runtime.executable_path = "/Applications/Factorio.app/Contents/MacOS/factorio"
   config.runtime.user_dir = "#{Dir.home}/Library/Application Support/factorio"
   config.runtime.data_dir = "/Applications/Factorio.app/Contents/data"

data/exe/factorix

@@ -8,6 +8,23 @@ require "zip"
 # Suppress warnings about invalid dates in ZIP files
 Zip.warn_invalid_date = false
 
+# Load config early, before dry-cli instantiates commands.
+# This is necessary because command classes use Import which resolves
+# dependencies at instantiation time (before CommandWrapper#call).
+# Without this, cache backends would use default config instead of user config.
+#
+# Note: --config-path option is handled separately in CommandWrapper and
+# will override settings if specified.
+config_path_index = ARGV.index("--config-path") || ARGV.index("-c")
+if config_path_index && ARGV[config_path_index + 1]
+  Factorix.load_config(Pathname(ARGV[config_path_index + 1]))
+elsif ENV["FACTORIX_CONFIG"]
+  Factorix.load_config(Pathname(ENV.fetch("FACTORIX_CONFIG")))
+else
+  default_config = Factorix::Container[:runtime].factorix_config_path
+  Factorix.load_config(default_config) if default_config.exist?
+end
+
 begin
   Dry::CLI.new(Factorix::CLI).call
   exit 0

data/lib/factorix/api/mod_download_api.rb

@@ -12,11 +12,9 @@ module Factorix
       # when FACTORIO_USERNAME/FACTORIO_TOKEN environment variables are not set.
       # It's resolved lazily via reader method instead.
       # @!parse
-      #   # @return [Transfer::Downloader]
-      #   attr_reader :downloader
       #   # @return [Dry::Logger::Dispatcher]
       #   attr_reader :logger
-      include Import[:downloader, :logger]
+      include Import[:logger]
 
       BASE_URL = "https://mods.factorio.com"
       private_constant :BASE_URL
@@ -34,24 +32,31 @@ module Factorix
       # @param download_url [String] relative download URL from API response (e.g., "/download/mod-name/...")
       # @param output [Pathname] output file path
       # @param expected_sha1 [String, nil] expected SHA1 digest for verification (optional)
+      # @param handler [Object, nil] event handler for download progress (optional)
       # @return [void]
       # @raise [ArgumentError] if download_url is not a relative path starting with "/"
       # @raise [DigestMismatchError] if SHA1 verification fails
-      def download(download_url, output, expected_sha1: nil)
+      def download(download_url, output, expected_sha1: nil, handler: nil)
         unless download_url.start_with?("/")
           logger.error("Invalid download_url", url: download_url)
           raise ArgumentError, "download_url must be a relative path starting with '/'"
         end
 
         uri = build_download_uri(download_url)
-        downloader.download(uri, output, expected_sha1:)
+        downloader = Container[:downloader]
+        downloader.subscribe(handler) if handler
+        begin
+          downloader.download(uri, output, expected_sha1:)
+        ensure
+          downloader.unsubscribe(handler) if handler
+        end
       end
 
       private def service_credential
         return @service_credential if defined?(@service_credential)
 
         @service_credential_mutex.synchronize do
-          @service_credential ||= Application[:service_credential]
+          @service_credential ||= Container[:service_credential]
         end
       end
 

data/lib/factorix/api/mod_info.rb

@@ -114,7 +114,7 @@ module Factorix
 
           URI(value)
         rescue URI::InvalidURIError => e
-          Application[:logger].warn("Skipping invalid URI '#{value}': #{e.message}")
+          Container[:logger].warn("Skipping invalid URI '#{value}': #{e.message}")
           nil
         end
       end
@@ -145,7 +145,7 @@ module Factorix
             Release[**r]
           rescue RangeError => e
             # Skip releases with invalid version numbers
-            Application[:logger].warn("Skipping release #{name}@#{r[:version]}: #{e.message}")
+            Container[:logger].warn("Skipping release #{name}@#{r[:version]}: #{e.message}")
             nil
           end
         }

data/lib/factorix/api/mod_management_api.rb

@@ -208,7 +208,7 @@ module Factorix
         return @api_credential if defined?(@api_credential)
 
         @api_credential_mutex.synchronize do
-          @api_credential ||= Application[:api_credential]
+          @api_credential ||= Container[:api_credential]
         end
       end
 

data/lib/factorix/api/mod_portal_api.rb

@@ -2,7 +2,6 @@
 
 require "erb"
 require "json"
-require "tempfile"
 require "uri"
 
 module Factorix
@@ -86,13 +85,13 @@ module Factorix
 
         # Invalidate get_mod cache
         mod_uri = build_uri("/api/mods/#{encoded_name}")
-        mod_key = cache.key_for(mod_uri.to_s)
-        cache.with_lock(mod_key) { cache.delete(mod_key) }
+        mod_cache_key = mod_uri.to_s
+        cache.with_lock(mod_cache_key) { cache.delete(mod_cache_key) }
 
         # Invalidate get_mod_full cache
         full_uri = build_uri("/api/mods/#{encoded_name}/full")
-        full_key = cache.key_for(full_uri.to_s)
-        cache.with_lock(full_key) { cache.delete(full_key) }
+        full_cache_key = full_uri.to_s
+        cache.with_lock(full_cache_key) { cache.delete(full_cache_key) }
 
         logger.debug("Invalidated cache for MOD", mod: mod_name)
       end
@@ -101,55 +100,13 @@ module Factorix
         URI.join(BASE_URL, path).tap {|uri| uri.query = URI.encode_www_form(params.sort.to_h) unless params.empty? }
       end
 
-      # Fetch data with cache support
+      # Fetch data from API (caching is handled by CacheDecorator in api_http_client)
       #
       # @param uri [URI::HTTPS] URI to fetch
       # @return [Hash{Symbol => untyped}] parsed JSON response with symbolized keys
       private def fetch_with_cache(uri)
-        key = cache.key_for(uri.to_s)
-
-        cached = cache.read(key, encoding: "UTF-8")
-        if cached
-          logger.debug("API cache hit", uri: uri.to_s)
-          return JSON.parse(cached, symbolize_names: true)
-        end
-
-        logger.debug("API cache miss", uri: uri.to_s)
-        response_body = fetch_from_api(uri)
-
-        store_in_cache(key, response_body)
-
-        JSON.parse(response_body, symbolize_names: true)
-      end
-
-      # Fetch data from API via HTTP
-      #
-      # @param uri [URI::HTTPS] URI to fetch
-      # @return [String] response body
-      # @raise [HTTPClientError] for 4xx errors
-      # @raise [HTTPServerError] for 5xx errors
-      private def fetch_from_api(uri)
-        logger.info("Fetching from API", uri: uri.to_s)
         response = client.get(uri)
-        logger.info("API response", code: response.code, size_bytes: response.body.bytesize)
-        response.body
-      end
-
-      # Store response body in cache via temporary file
-      #
-      # @param key [String] cache key
-      # @param data [String] response body
-      # @return [void]
-      private def store_in_cache(key, data)
-        temp_file = Tempfile.new("cache")
-        begin
-          temp_file.write(data)
-          temp_file.close
-          cache.store(key, Pathname(temp_file.path))
-          logger.debug("Stored API response in cache", key:)
-        ensure
-          temp_file.unlink
-        end
+        JSON.parse((+response.body).force_encoding(Encoding::UTF_8), symbolize_names: true)
       end
 
       # Validate page_size parameter

data/lib/factorix/api_credential.rb

@@ -22,7 +22,7 @@ module Factorix
     # @return [APICredential] new instance with API key from environment
     # @raise [CredentialError] if API key is not set in environment
     def self.load
-      logger = Application["logger"]
+      logger = Container["logger"]
       logger.debug "Loading API credentials from environment"
 
       api_key = ENV.fetch(ENV_API_KEY, nil)

data/lib/factorix/cache/base.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Cache
+    # Abstract base class for cache backends.
+    #
+    # All cache backends (FileSystem, S3, Redis) inherit from this class
+    # and implement the abstract methods defined here.
+    #
+    # @abstract Subclasses must implement all abstract methods.
+    class Base
+      # @return [Integer, nil] time-to-live in seconds (nil for unlimited)
+      attr_reader :ttl
+
+      # Initialize a new cache backend.
+      #
+      # @param ttl [Integer, nil] time-to-live in seconds (nil for unlimited)
+      def initialize(ttl: nil)
+        @ttl = ttl
+      end
+
+      # Check if a cache entry exists and is not expired.
+      #
+      # @param key [String] logical cache key
+      # @return [Boolean] true if the cache entry exists and is valid
+      # @abstract
+      def exist?(key) = raise NotImplementedError, "#{self.class}#exist? must be implemented"
+
+      # Read a cached entry as a string.
+      #
+      # @param key [String] logical cache key
+      # @return [String, nil] cached content or nil if not found/expired
+      # @abstract
+      def read(key) = raise NotImplementedError, "#{self.class}#read must be implemented"
+
+      # Write cached content to a file.
+      #
+      # Unlike {#read} which returns content as a String, this method writes
+      # directly to a file path, which is more memory-efficient for large files.
+      #
+      # @param key [String] logical cache key
+      # @param output [Pathname] path to write the cached content
+      # @return [Boolean] true if written successfully, false if not found/expired
+      # @abstract
+      def write_to(key, output) = raise NotImplementedError, "#{self.class}#write_to must be implemented"
+
+      # Store data in the cache.
+      #
+      # @param key [String] logical cache key
+      # @param src [Pathname] path to the source file
+      # @return [Boolean] true if stored successfully
+      # @abstract
+      def store(key, src) = raise NotImplementedError, "#{self.class}#store must be implemented"
+
+      # Delete a cache entry.
+      #
+      # @param key [String] logical cache key
+      # @return [Boolean] true if deleted, false if not found
+      # @abstract
+      def delete(key) = raise NotImplementedError, "#{self.class}#delete must be implemented"
+
+      # Clear all cache entries.
+      #
+      # @return [void]
+      # @abstract
+      def clear = raise NotImplementedError, "#{self.class}#clear must be implemented"
+
+      # Execute a block with an exclusive lock on the cache entry.
+      #
+      # @param key [String] logical cache key
+      # @yield block to execute with lock held
+      # @abstract
+      def with_lock(key) = raise NotImplementedError, "#{self.class}#with_lock must be implemented"
+
+      # Get the age of a cache entry in seconds.
+      #
+      # @param key [String] logical cache key
+      # @return [Float, nil] age in seconds, or nil if entry doesn't exist
+      # @abstract
+      def age(key) = raise NotImplementedError, "#{self.class}#age must be implemented"
+
+      # Check if a cache entry has expired based on TTL.
+      #
+      # @param key [String] logical cache key
+      # @return [Boolean] true if expired, false otherwise
+      # @abstract
+      def expired?(key) = raise NotImplementedError, "#{self.class}#expired? must be implemented"
+
+      # Get the size of a cached entry in bytes.
+      #
+      # @param key [String] logical cache key
+      # @return [Integer, nil] size in bytes, or nil if entry doesn't exist/expired
+      # @abstract
+      def size(key) = raise NotImplementedError, "#{self.class}#size must be implemented"
+
+      # Enumerate cache entries.
+      #
+      # Yields [key, entry] pairs similar to Hash#each.
+      #
+      # @yield [key, entry] logical key and Entry object
+      # @yieldparam key [String] logical cache key
+      # @yieldparam entry [Entry] cache entry metadata
+      # @return [Enumerator] if no block given
+      # @abstract
+      def each = raise NotImplementedError, "#{self.class}#each must be implemented"
+
+      # Return backend-specific information.
+      #
+      # Subclasses should override this method to provide configuration details
+      # specific to their backend implementation.
+      #
+      # @return [Hash] backend-specific information (empty by default)
+      def backend_info = {}
+    end
+  end
+end

data/lib/factorix/cache/entry.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Factorix
+  module Cache
+    Entry = Data.define(:size, :age, :expired)
+
+    # Represents a cache entry for enumeration operations.
+    #
+    # Used by {Base#each} to yield entry metadata alongside keys.
+    # Note: The key is NOT included in Entry; it is yielded separately.
+    #
+    # @!attribute [r] size
+    #   @return [Integer] entry size in bytes
+    # @!attribute [r] age
+    #   @return [Float] age in seconds since creation/modification
+    class Entry
+      private :expired
+
+      # Check if the cache entry has expired.
+      #
+      # @return [Boolean] true if entry has exceeded TTL
+      def expired? = expired
+    end
+  end
+end