factorix 0.5.1 → 0.7.0

data/lib/factorix/http/cache_decorator.rb

@@ -50,9 +50,9 @@ module Factorix
         # Don't cache streaming requests
         return client.get(uri, headers:, &block) if block
 
-        key = cache.key_for(uri.to_s)
+        cache_key = uri.to_s
 
-        cached_body = cache.read(key)
+        cached_body = cache.read(cache_key)
         if cached_body
           logger.debug("Cache hit", uri: uri.to_s)
           publish("cache.hit", url: uri.to_s)
@@ -63,9 +63,9 @@ module Factorix
         publish("cache.miss", url: uri.to_s)
 
         # Locking prevents concurrent downloads of the same resource
-        cache.with_lock(key) do
+        cache.with_lock(cache_key) do
           # Double-check: another thread might have filled the cache
-          cached_body = cache.read(key)
+          cached_body = cache.read(cache_key)
           if cached_body
             publish("cache.hit", url: uri.to_s)
             return CachedResponse.new(cached_body)
@@ -77,7 +77,7 @@ module Factorix
             with_temporary_file do |temp|
               temp.write(response.body)
               temp.close
-              cache.store(key, Pathname(temp.path))
+              cache.store(cache_key, Pathname(temp.path))
             end
           end
 

data/lib/factorix/http/client.rb

@@ -162,9 +162,9 @@ module Factorix
         Net::HTTP.new(uri.host, uri.port).tap do |http|
           http.use_ssl = uri.scheme == "https"
           http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-          http.open_timeout = Application.config.http.connect_timeout
-          http.read_timeout = Application.config.http.read_timeout
-          http.write_timeout = Application.config.http.write_timeout if http.respond_to?(:write_timeout=)
+          http.open_timeout = Factorix.config.http.connect_timeout
+          http.read_timeout = Factorix.config.http.read_timeout
+          http.write_timeout = Factorix.config.http.write_timeout if http.respond_to?(:write_timeout=)
         end
       end
 

data/lib/factorix/info_json.rb

@@ -47,21 +47,21 @@ module Factorix
     # @return [InfoJSON] parsed info.json from zip
     # @raise [FileFormatError] if zip is invalid or info.json not found
     def self.from_zip(zip_path)
-      cache = Application.resolve(:info_json_cache)
-      logger = Application.resolve(:logger)
-      cache_key = cache.key_for(zip_path.to_s)
+      cache = Container.resolve(:info_json_cache)
+      logger = Container.resolve(:logger)
+      cache_key = zip_path.to_s
 
-      if (cached_json = cache.read(cache_key, encoding: Encoding::UTF_8))
+      if (cached_json = cache.read(cache_key))
         logger.debug("info.json cache hit", path: zip_path.to_s)
-        return from_json(cached_json)
+        return from_json((+cached_json).force_encoding(Encoding::UTF_8))
       end
 
       logger.debug("info.json cache miss", path: zip_path.to_s)
 
       cache.with_lock(cache_key) do
-        if (cached_json = cache.read(cache_key, encoding: Encoding::UTF_8))
+        if (cached_json = cache.read(cache_key))
           logger.debug("info.json cache hit (after lock)", path: zip_path.to_s)
-          return from_json(cached_json)
+          return from_json((+cached_json).force_encoding(Encoding::UTF_8))
         end
 
         json_string = Zip::File.open(zip_path) {|zip_file|

data/lib/factorix/mod_list.rb

@@ -18,7 +18,7 @@ module Factorix
     # @param path [Pathname] the path to the file to load the MOD list from (default: runtime.mod_list_path)
     # @return [Factorix::MODList] the loaded MOD list
     # @raise [MODSettingsError] if the base MOD is disabled
-    def self.load(path=Application[:runtime].mod_list_path)
+    def self.load(path=Container[:runtime].mod_list_path)
       raw_data = JSON.parse(path.read, symbolize_names: true)
       mods_hash = raw_data[:mods].to_h {|entry|
         mod = MOD[name: entry[:name]]
@@ -50,7 +50,7 @@ module Factorix
     #
     # @param path [Pathname] the path to the file to save the MOD list to (default: runtime.mod_list_path)
     # @return [void]
-    def save(path=Application[:runtime].mod_list_path)
+    def save(path=Container[:runtime].mod_list_path)
       mods_data = @mods.map {|mod, state|
         data = {name: mod.name, enabled: state.enabled?}
         # Only include version in the output if it exists

data/lib/factorix/mod_settings.rb

@@ -108,7 +108,7 @@ module Factorix
     #
     # @param path [Pathname] Path to the MOD settings file (default: runtime.mod_settings_path)
     # @return [MODSettings] New MODSettings instance
-    def self.load(path=Application[:runtime].mod_settings_path)
+    def self.load(path=Container[:runtime].mod_settings_path)
       path.open("rb") do |io|
         game_version, sections = load_settings_from_io(io)
         new(game_version, sections)
@@ -244,7 +244,7 @@ module Factorix
     #
     # @param path [Pathname] Path to save the MOD settings file (default: runtime.mod_settings_path)
     # @return [void]
-    def save(path=Application[:runtime].mod_settings_path)
+    def save(path=Container[:runtime].mod_settings_path)
       path.open("wb") do |file|
         serializer = SerDes::Serializer.new(file)
 

data/lib/factorix/portal.rb

@@ -72,12 +72,13 @@ module Factorix
     #
     # @param release [API::Release] release object containing download_url and sha1
     # @param output [Pathname] output file path
+    # @param handler [Object, nil] event handler for download progress (optional)
     # @return [void]
     # @raise [DigestMismatchError] if SHA1 verification fails
-    def download_mod(release, output)
+    def download_mod(release, output, handler: nil)
       # Extract path from URI::HTTPS
       download_path = release.download_url.path
-      mod_download_api.download(download_path, output, expected_sha1: release.sha1)
+      mod_download_api.download(download_path, output, expected_sha1: release.sha1, handler:)
     end
 
     # Upload a MOD file to the portal

data/lib/factorix/runtime/user_configurable.rb

@@ -8,10 +8,10 @@ module Factorix
     # auto-detected paths via configuration. When a configured path is available,
     # it is used instead of platform-specific auto-detection.
     #
-    # Configuration is done via Application.config:
+    # Configuration is done via Factorix.config:
     #
     # @example Configure paths in config file
-    #   Factorix::Application.configure do |config|
+    #   Factorix.configure do |config|
     #     config.runtime.executable_path = "/opt/factorio/bin/x64/factorio"
     #     config.runtime.user_dir = "/home/user/.factorio"
     #   end
@@ -46,20 +46,20 @@ module Factorix
       def data_dir = configurable_path(:data_dir, example_path: "/path/to/factorio/data") { super }
 
       private def configurable_path(name, example_path:)
-        if (configured = Application.config.runtime.public_send(name))
-          Application[:logger].debug("Using configured #{name}", path: configured.to_s)
+        if (configured = Factorix.config.runtime.public_send(name))
+          Container[:logger].debug("Using configured #{name}", path: configured.to_s)
           configured
         else
-          Application[:logger].debug("No configuration for #{name}, using auto-detection")
-          yield.tap {|path| Application[:logger].debug("Auto-detected #{name}", path: path.to_s) }
+          Container[:logger].debug("No configuration for #{name}, using auto-detection")
+          yield.tap {|path| Container[:logger].debug("Auto-detected #{name}", path: path.to_s) }
         end
       rescue NotImplementedError => e
-        Application[:logger].error("Auto-detection failed and no configuration provided", error: e.message)
+        Container[:logger].error("Auto-detection failed and no configuration provided", error: e.message)
         raise ConfigurationError, <<~MESSAGE
           #{name} not configured and auto-detection is not supported for this platform.
-          Please configure it in #{Application[:runtime].factorix_config_path}:
+          Please configure it in #{Container[:runtime].factorix_config_path}:
 
-            Factorix::Application.configure do |config|
+            Factorix.configure do |config|
               config.runtime.#{name} = "#{example_path}"
             end
         MESSAGE

data/lib/factorix/service_credential.rb

@@ -39,7 +39,7 @@ module Factorix
       elsif username_env || token_env
         raise CredentialError, "Both #{ENV_USERNAME} and #{ENV_TOKEN} must be set (or neither)"
       else
-        runtime = Application[:runtime]
+        runtime = Container[:runtime]
         from_player_data(runtime:)
       end
     end
@@ -49,7 +49,7 @@ module Factorix
     # @return [ServiceCredential] new instance with credentials from environment
     # @raise [CredentialError] if username or token is not set or empty
     def self.from_env
-      logger = Application["logger"]
+      logger = Container["logger"]
       logger.debug "Loading service credentials from environment"
 
       username = ENV.fetch(ENV_USERNAME, nil)
@@ -83,7 +83,7 @@ module Factorix
     # @raise [Errno::ENOENT] if player-data.json does not exist
     # @raise [CredentialError] if username or token is missing in player-data.json
     def self.from_player_data(runtime:)
-      logger = Application["logger"]
+      logger = Container["logger"]
       logger.debug "Loading service credentials from player-data.json"
 
       player_data_path = runtime.player_data_path

data/lib/factorix/transfer/downloader.rb

@@ -53,9 +53,9 @@ module Factorix
         end
 
         logger.info("Starting download", output: output.to_s)
-        key = cache.key_for(url.to_s)
+        cache_key = strip_query(url)
 
-        case try_cache_hit(key, output, expected_sha1:)
+        case try_cache_hit(cache_key, output, expected_sha1:)
         when :hit
           return
         when :miss
@@ -68,14 +68,14 @@ module Factorix
           raise RuntimeError, "Unexpected cache state"
         end
 
-        cache.with_lock(key) do
-          return if try_cache_hit(key, output, expected_sha1:) == :hit
+        cache.with_lock(cache_key) do
+          return if try_cache_hit(cache_key, output, expected_sha1:) == :hit
 
           with_temporary_file do |temp_file|
             download_file_with_progress(url, temp_file)
             verify_sha1(temp_file, expected_sha1) if expected_sha1
-            cache.store(key, temp_file)
-            cache.fetch(key, output)
+            cache.store(cache_key, temp_file)
+            cache.write_to(cache_key, output)
           end
         end
       end
@@ -112,21 +112,21 @@ module Factorix
       # If the cached file exists but fails SHA1 verification, the cache entry
       # is invalidated and :corrupted is returned to trigger re-download.
       #
-      # @param key [String] cache key
+      # @param cache_key [String] logical cache key (URL string)
       # @param output [Pathname] path to save the cached file
       # @param expected_sha1 [String, nil] expected SHA1 digest for verification (optional)
       # @return [Symbol] :hit if cache hit with valid SHA1, :miss if not cached, :corrupted if SHA1 mismatch
-      private def try_cache_hit(key, output, expected_sha1:)
-        return :miss unless cache.fetch(key, output)
+      private def try_cache_hit(cache_key, output, expected_sha1:)
+        return :miss unless cache.write_to(cache_key, output)
 
         logger.info("Cache hit", output: output.to_s)
         verify_sha1(output, expected_sha1) if expected_sha1
-        total_size = cache.size(key)
+        total_size = cache.size(cache_key)
         publish("cache.hit", output: output.to_s, total_size:)
         :hit
       rescue DigestMismatchError => e
         logger.warn("Cache corrupted, invalidating", output: output.to_s, error: e.message)
-        cache.delete(key)
+        cache.delete(cache_key)
         :corrupted
       end
 
@@ -144,6 +144,14 @@ module Factorix
         raise DigestMismatchError, "SHA1 mismatch: expected #{expected_sha1}, got #{actual_sha1}"
       end
 
+      # Strip query parameters from a URI to create a safe cache key.
+      # This prevents sensitive data (e.g., authentication tokens) from being
+      # stored in cache metadata.
+      #
+      # @param uri [URI] the URI to strip
+      # @return [String] URI string without query parameters
+      private def strip_query(uri) = uri.dup.tap {|u| u.query = nil }.to_s
+
       # Create a temporary file for downloading, ensuring cleanup after use.
       #
       # @yield [Pathname] the temporary file path

data/lib/factorix/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Factorix
-  VERSION = "0.5.1"
+  VERSION = "0.7.0"
   public_constant :VERSION
 end

data/lib/factorix.rb

@@ -1,13 +1,122 @@
 # frozen_string_literal: true
 
 require "dry/auto_inject"
+require "dry/configurable"
 require "zeitwerk"
 require_relative "factorix/errors"
 require_relative "factorix/version"
 
 # Factorix provides a CLI for Factorio MOD management, settings synchronization,
 # and MOD Portal integration.
+#
+# @example Configure Factorix
+#   Factorix.configure do |config|
+#     config.log_level = :debug
+#     config.http.connect_timeout = 10
+#   end
 module Factorix
+  extend Dry::Configurable
+
+  # Log level (:debug, :info, :warn, :error, :fatal)
+  setting :log_level, default: :info
+
+  # Runtime settings (optional overrides for auto-detection)
+  setting :runtime do
+    setting :executable_path, constructor: ->(v) { v ? Pathname(v) : nil }
+    setting :user_dir, constructor: ->(v) { v ? Pathname(v) : nil }
+    setting :data_dir, constructor: ->(v) { v ? Pathname(v) : nil }
+  end
+
+  # HTTP timeout settings
+  setting :http do
+    setting :connect_timeout, default: 5
+    setting :read_timeout, default: 30
+    setting :write_timeout, default: 30
+  end
+
+  # Cache settings
+  # Each cache type can have its own backend with hierarchical configuration.
+  # Common settings (backend, ttl) apply to all backends.
+  # Backend-specific settings are nested under the backend name.
+  setting :cache do
+    # Download cache settings (for MOD files)
+    setting :download do
+      setting :backend, default: :file_system
+      setting :ttl, default: nil # nil for unlimited (MOD files are immutable)
+      setting :file_system do
+        setting :max_file_size, default: nil # nil for unlimited
+        setting :compression_threshold, default: nil # nil for no compression (binary files)
+      end
+      setting :redis do
+        setting :url, default: nil # nil falls back to REDIS_URL env, then localhost:6379
+        setting :lock_timeout, default: 30
+      end
+      setting :s3 do
+        setting :bucket, default: nil # required when using S3 backend
+        setting :region, default: nil # nil falls back to AWS_REGION env or SDK default
+        setting :lock_timeout, default: 30
+      end
+    end
+
+    # API cache settings (for API responses)
+    setting :api do
+      setting :backend, default: :file_system
+      setting :ttl, default: 3600 # 1 hour (API responses may change)
+      setting :file_system do
+        setting :max_file_size, default: 10 * 1024 * 1024 # 10MiB (JSON responses)
+        setting :compression_threshold, default: 0 # always compress (JSON is highly compressible)
+      end
+      setting :redis do
+        setting :url, default: nil # nil falls back to REDIS_URL env, then localhost:6379
+        setting :lock_timeout, default: 30
+      end
+      setting :s3 do
+        setting :bucket, default: nil # required when using S3 backend
+        setting :region, default: nil # nil falls back to AWS_REGION env or SDK default
+        setting :lock_timeout, default: 30
+      end
+    end
+
+    # info.json cache settings (for MOD metadata from ZIP files)
+    setting :info_json do
+      setting :backend, default: :file_system
+      setting :ttl, default: nil # nil for unlimited (info.json is immutable within a MOD ZIP)
+      setting :file_system do
+        setting :max_file_size, default: nil # nil for unlimited (info.json is small)
+        setting :compression_threshold, default: 0 # always compress (JSON is highly compressible)
+      end
+      setting :redis do
+        setting :url, default: nil # nil falls back to REDIS_URL env, then localhost:6379
+        setting :lock_timeout, default: 30
+      end
+      setting :s3 do
+        setting :bucket, default: nil # required when using S3 backend
+        setting :region, default: nil # nil falls back to AWS_REGION env or SDK default
+        setting :lock_timeout, default: 30
+      end
+    end
+  end
+
+  # Load configuration from file
+  #
+  # @param path [Pathname, nil] configuration file path
+  # @return [void]
+  # @raise [ConfigurationError] if explicitly specified path does not exist
+  def self.load_config(path=nil)
+    if path
+      # Explicitly specified path must exist
+      raise ConfigurationError, "Configuration file not found: #{path}" unless path.exist?
+
+      config_path = path
+    else
+      # Default path is optional
+      config_path = Container.resolve(:runtime).factorix_config_path
+      return unless config_path.exist?
+    end
+
+    instance_eval(config_path.read, config_path.to_s)
+  end
+
   loader = Zeitwerk::Loader.for_gem
   loader.ignore("#{__dir__}/factorix/version.rb")
   loader.ignore("#{__dir__}/factorix/errors.rb")
@@ -33,6 +142,6 @@ module Factorix
   )
   loader.setup
 
-  Import = Dry::AutoInject(Application)
+  Import = Dry::AutoInject(Container)
   public_constant :Import
 end

data/sig/factorix/api/mod_download_api.rbs

@@ -7,12 +7,11 @@ module Factorix
     class MODDownloadAPI
       BASE_URL: String
 
-      attr_reader downloader: Transfer::Downloader
       attr_reader logger: Dry::Logger::Dispatcher
 
       def initialize: (**untyped deps) -> void
 
-      def download: (String download_url, Pathname output, ?expected_sha1: String?) -> void
+      def download: (String download_url, Pathname output, ?expected_sha1: String?, ?handler: untyped?) -> void
     end
   end
 end

data/sig/factorix/cache/base.rbs

@@ -0,0 +1,28 @@
+# RBS type signature file
+
+module Factorix
+  module Cache
+    class Base
+      attr_reader ttl: Integer?
+
+      def initialize: (?ttl: Integer?) -> void
+
+      def exist?: (String key) -> bool
+      def read: (String key) -> String?
+      def store: (String key, Pathname src) -> bool
+      def delete: (String key) -> bool
+      def clear: () -> void
+
+      def with_lock: (String key) { () -> void } -> void
+
+      def age: (String key) -> Float?
+      def expired?: (String key) -> bool
+      def size: (String key) -> Integer?
+
+      def each: () -> Enumerator[[String, Entry], void]
+              | () { ([String, Entry]) -> void } -> void
+
+      def backend_info: () -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/factorix/cache/entry.rbs

@@ -0,0 +1,14 @@
+# RBS type signature file
+
+module Factorix
+  module Cache
+    class Entry
+      attr_reader size: Integer
+      attr_reader age: Float
+
+      def expired?: () -> bool
+
+      def initialize: (size: Integer, age: Float, expired: bool) -> void
+    end
+  end
+end

data/sig/factorix/cache/file_system.rbs

@@ -4,18 +4,16 @@
 
 module Factorix
   module Cache
-    class FileSystem
+    class FileSystem < Base
       LOCK_FILE_LIFETIME: Integer
 
-      def initialize: (Pathname cache_dir, ?ttl: Integer?, ?max_file_size: Integer?, ?compression_threshold: Integer?) -> void
-
-      def key_for: (String url_string) -> String
+      def initialize: (cache_type: Symbol, ?ttl: Integer?, ?max_file_size: Integer?, ?compression_threshold: Integer?) -> void
 
       def exist?: (String key) -> bool
 
-      def fetch: (String key, Pathname output) -> bool
+      def write_to: (String key, Pathname output) -> bool
 
-      def read: (String key, ?encoding: Encoding | String) -> String?
+      def read: (String key) -> String?
 
       def store: (String key, Pathname src) -> bool
 
@@ -30,6 +28,9 @@ module Factorix
       def size: (String key) -> Integer?
 
       def with_lock: [T] (String key) { () -> T } -> T
+
+      def each: () { (String, Entry) -> void } -> void
+              | () -> Enumerator[[String, Entry], void]
     end
   end
 end

data/sig/factorix/cache/redis.rbs

@@ -0,0 +1,36 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module Cache
+    class Redis < Base
+      DEFAULT_LOCK_TIMEOUT: Integer
+
+      def initialize: (?url: String?, cache_type: String | Symbol, ?lock_timeout: Integer, ?ttl: Integer?) -> void
+
+      def exist?: (String key) -> bool
+
+      def read: (String key) -> String?
+
+      def write_to: (String key, Pathname output) -> bool
+
+      def store: (String key, Pathname src) -> bool
+
+      def delete: (String key) -> bool
+
+      def clear: () -> void
+
+      def age: (String key) -> Integer?
+
+      def expired?: (String key) -> bool
+
+      def size: (String key) -> Integer?
+
+      def with_lock: [T] (String key) { () -> T } -> T
+
+      def each: () { (String, Entry) -> void } -> void
+              | () -> Enumerator[[String, Entry], void]
+    end
+  end
+end

data/sig/factorix/cache/s3.rbs

@@ -0,0 +1,38 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  module Cache
+    class S3 < Base
+      DEFAULT_LOCK_TIMEOUT: Integer
+
+      def initialize: (bucket: String, cache_type: String | Symbol, ?region: String?, ?lock_timeout: Integer, ?ttl: Integer?) -> void
+
+      def exist?: (String key) -> bool
+
+      def read: (String key) -> String?
+
+      def write_to: (String key, Pathname output) -> bool
+
+      def store: (String key, Pathname src) -> bool
+
+      def delete: (String key) -> bool
+
+      def clear: () -> void
+
+      def age: (String key) -> Integer?
+
+      def expired?: (String key) -> bool
+
+      def size: (String key) -> Integer?
+
+      def with_lock: [T] (String key) { () -> T } -> T
+
+      def each: () { (String, Entry) -> void } -> void
+              | () -> Enumerator[[String, Entry], void]
+
+      def backend_info: () -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/factorix/container.rbs

@@ -0,0 +1,15 @@
+# RBS type signature file
+# NOTE: Do not include private method definitions in RBS files.
+#       Only public interfaces should be documented here.
+
+module Factorix
+  class Container
+    extend Dry::Core::Container::Mixin
+
+    def self.register: (Symbol, ?memoize: bool) { () -> untyped } -> void
+
+    def self.resolve: (Symbol) -> untyped
+
+    def self.[]: (Symbol) -> untyped
+  end
+end

data/sig/factorix/errors.rbs

@@ -49,6 +49,9 @@ module Factorix
   class HTTPServerError < HTTPError
   end
 
+  class LockTimeoutError < InfrastructureError
+  end
+
   class DigestMismatchError < InfrastructureError
   end
 

data/sig/factorix/portal.rbs

@@ -18,7 +18,7 @@ module Factorix
 
     def get_mod_full: (String name) -> API::MODInfo
 
-    def download_mod: (API::Release release, Pathname output) -> void
+    def download_mod: (API::Release release, Pathname output, ?handler: untyped?) -> void
 
     def upload_mod: (String mod_name, Pathname file_path, **untyped metadata) -> void