factorix 0.5.0

data/lib/factorix/api/tag.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Factorix
+  module API
+    Tag = Data.define(:value, :name, :description)
+
+    # Tag object from MOD Portal API
+    #
+    # Represents a MOD tag with value, name, and description.
+    # Uses flyweight pattern - same tag value returns same instance.
+    #
+    # @see https://wiki.factorio.com/Mod_portal_API#Tags
+    class Tag
+      # @!attribute [r] value
+      #   @return [String] tag value (e.g., "transportation", "logistics")
+      # @!attribute [r] name
+      #   @return [String] human-readable tag name (e.g., "Transportation", "Logistics")
+      # @!attribute [r] description
+      #   @return [String] tag description
+
+      # Predefined tag instances
+      TRANSPORTATION = new(value: "transportation", name: "Transportation", description: "Transportation of the player, be it vehicles or teleporters.")
+      private_constant :TRANSPORTATION
+      LOGISTICS = new(value: "logistics", name: "Logistics", description: "Augmented or new ways of transporting materials - belts, inserters, pipes!")
+      private_constant :LOGISTICS
+      TRAINS = new(value: "trains", name: "Trains", description: "Trains are great, but what if they could do even more?")
+      private_constant :TRAINS
+      COMBAT = new(value: "combat", name: "Combat", description: "New ways to deal with enemies, be it attack or defense.")
+      private_constant :COMBAT
+      ARMOR = new(value: "armor", name: "Armor", description: "Armors or armor equipment.")
+      private_constant :ARMOR
+      ENEMIES = new(value: "enemies", name: "Enemies", description: "Changes to enemies or entirely new enemies to deal with.")
+      private_constant :ENEMIES
+      CHARACTER = new(value: "character", name: "Character", description: "Changes to the player's in-game appearance.")
+      private_constant :CHARACTER
+      ENVIRONMENT = new(value: "environment", name: "Environment", description: "Map generation and terrain modification.")
+      private_constant :ENVIRONMENT
+      PLANETS = new(value: "planets", name: "Planets", description: "New places to build more factories.")
+      private_constant :PLANETS
+      MINING = new(value: "mining", name: "Mining", description: "New ores and resources as well as machines.")
+      private_constant :MINING
+      FLUIDS = new(value: "fluids", name: "Fluids", description: "Things related to oil and other fluids.")
+      private_constant :FLUIDS
+      LOGISTIC_NETWORK = new(value: "logistic-network", name: "Logistics Network", description: "Related to roboports and logistic robots")
+      private_constant :LOGISTIC_NETWORK
+      CIRCUIT_NETWORK = new(value: "circuit-network", name: "Circuit network", description: "Entities which interact with the circuit network.")
+      private_constant :CIRCUIT_NETWORK
+      MANUFACTURING = new(value: "manufacturing", name: "Manufacture", description: "Furnaces, assembling machines, production chains")
+      private_constant :MANUFACTURING
+      POWER = new(value: "power", name: "Power Production", description: "Changes to power production and distribution.")
+      private_constant :POWER
+      STORAGE = new(value: "storage", name: "Storage", description: "More than just chests.")
+      private_constant :STORAGE
+      BLUEPRINTS = new(value: "blueprints", name: "Blueprints", description: "Change blueprint behavior.")
+      private_constant :BLUEPRINTS
+      CHEATS = new(value: "cheats", name: "Cheats", description: "Play it your way.")
+      private_constant :CHEATS
+
+      # Lookup table for flyweight pattern
+      TAGS = {
+        "transportation" => TRANSPORTATION,
+        "logistics" => LOGISTICS,
+        "trains" => TRAINS,
+        "combat" => COMBAT,
+        "armor" => ARMOR,
+        "enemies" => ENEMIES,
+        "character" => CHARACTER,
+        "environment" => ENVIRONMENT,
+        "planets" => PLANETS,
+        "mining" => MINING,
+        "fluids" => FLUIDS,
+        "logistic-network" => LOGISTIC_NETWORK,
+        "circuit-network" => CIRCUIT_NETWORK,
+        "manufacturing" => MANUFACTURING,
+        "power" => POWER,
+        "storage" => STORAGE,
+        "blueprints" => BLUEPRINTS,
+        "cheats" => CHEATS
+      }.freeze
+      private_constant :TAGS
+
+      # Get Tag instance for the given value
+      #
+      # Returns predefined instance for known tags (flyweight pattern).
+      # Raises an error for unknown tag values.
+      #
+      # @param value [String] tag value
+      # @return [Tag] Tag instance
+      # @raise [KeyError] if tag value is unknown
+      def self.for(value) = TAGS.fetch(value.to_s)
+
+      private_class_method :new, :[]
+    end
+  end
+end

data/lib/factorix/api.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Factorix
+  # API layer for Factorio MOD Portal
+  module API
+  end
+end

data/lib/factorix/api_credential.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Factorix
+  APICredential = Data.define(:api_key)
+
+  # API credentials for Factorio MOD Portal management
+  #
+  # @see https://wiki.factorio.com/Mod_upload_API
+  # @see https://wiki.factorio.com/Mod_publish_API
+  # @see https://wiki.factorio.com/Mod_details_API
+  # @see https://wiki.factorio.com/Mod_images_API
+  class APICredential
+    # @!attribute [r] api_key
+    #   @return [String] API key for Factorio MOD Portal
+
+    # Environment variable name for API key
+    ENV_API_KEY = "FACTORIO_API_KEY"
+    private_constant :ENV_API_KEY
+
+    # Load API credentials from environment variables
+    #
+    # @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.debug "Loading API credentials from environment"
+
+      api_key = ENV.fetch(ENV_API_KEY, nil)
+      if api_key.nil?
+        logger.error("Failed to load API credentials", reason: "#{ENV_API_KEY} not set")
+        raise CredentialError, "#{ENV_API_KEY} environment variable is not set"
+      end
+
+      if api_key.empty?
+        logger.error("Failed to load API credentials", reason: "#{ENV_API_KEY} is empty")
+        raise CredentialError, "#{ENV_API_KEY} environment variable is empty"
+      end
+
+      logger.info("API credentials loaded successfully")
+      new(api_key:)
+    end
+
+    private_class_method :new, :[]
+
+    # @return [String] string representation with masked API key
+    def inspect = %[#<#{self.class} api_key="*****">]
+
+    alias to_s inspect
+
+    # @param pp [PP] pretty printer
+    # @return [void]
+    def pretty_print(pp) = pp.text(inspect)
+  end
+end

data/lib/factorix/application.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+require "dry/core"
+require "dry/logger"
+
+module Factorix
+  # Application container and configuration
+  #
+  # Provides dependency injection container and configuration management
+  # using dry-core's Container and dry-configurable.
+  #
+  # @example Configure the application
+  #   Factorix::Application.configure do |config|
+  #     config.log_level = :debug
+  #     config.http.connect_timeout = 10
+  #   end
+  #
+  # @example Resolve dependencies
+  #   runtime = Factorix::Application[:runtime]
+  class Application
+    extend Dry::Core::Container::Mixin
+    extend Dry::Configurable
+
+    # Some items are registered with memoize: false to support independent event handlers
+    # for each parallel download task (e.g., progress tracking).
+    # Items registered with memoize: false:
+    # - :downloader (event handlers for progress tracking)
+    # - :mod_download_api (contains :downloader)
+    # - :portal (contains :mod_download_api)
+
+    # Register runtime detector
+    register(:runtime, memoize: true) do
+      Runtime.detect
+    end
+
+    # Register logger
+    register(:logger, memoize: true) do
+      runtime = resolve(:runtime)
+      log_path = runtime.factorix_log_path
+
+      # Ensure log directory exists
+      log_path.dirname.mkpath unless log_path.dirname.exist?
+
+      # Create logger with file backend
+      # Dispatcher level set to DEBUG to allow all messages through
+      # Backend controls filtering based on --log-level option
+      Dry.Logger(:factorix, level: :debug) do |dispatcher|
+        dispatcher.add_backend(level: config.log_level, stream: log_path.to_s, template: "[%<time>s] %<severity>s: %<message>s %<payload>s")
+      end
+    end
+
+    # Register retry strategy for network operations
+    register(:retry_strategy, memoize: true) do
+      HTTP::RetryStrategy.new
+    end
+
+    # Register download cache
+    register(:download_cache, memoize: true) do
+      c = config.cache.download
+      Cache::FileSystem.new(c.dir, **c.to_h.except(:dir))
+    end
+
+    # Register API cache (with compression for JSON responses)
+    register(:api_cache, memoize: true) do
+      c = config.cache.api
+      Cache::FileSystem.new(c.dir, **c.to_h.except(:dir))
+    end
+
+    # Register info.json cache (for MOD metadata from ZIP files)
+    register(:info_json_cache, memoize: true) do
+      c = config.cache.info_json
+      Cache::FileSystem.new(c.dir, **c.to_h.except(:dir))
+    end
+
+    # Register base HTTP client
+    register(:http_client, memoize: true) do
+      HTTP::Client.new(masked_params: %w[username token secure])
+    end
+
+    # Register decorated HTTP client for downloads (with retry only)
+    # Note: Caching is handled by Downloader, not at HTTP client level
+    register(:download_http_client, memoize: true) do
+      client = resolve(:http_client)
+      retry_strategy = resolve(:retry_strategy)
+
+      # Decorate: Client -> Retry (no cache, handled by Downloader)
+      HTTP::RetryDecorator.new(client:, retry_strategy:)
+    end
+
+    # Register decorated HTTP client for API calls (with retry + cache)
+    register(:api_http_client, memoize: true) do
+      client = resolve(:http_client)
+      api_cache = resolve(:api_cache)
+      retry_strategy = resolve(:retry_strategy)
+
+      # Decorate: Client -> Cache -> Retry
+      cached = HTTP::CacheDecorator.new(client:, cache: api_cache)
+      HTTP::RetryDecorator.new(client: cached, retry_strategy:)
+    end
+
+    # Register decorated HTTP client for uploads (with retry only, no cache)
+    register(:upload_http_client, memoize: true) do
+      client = resolve(:http_client)
+      retry_strategy = resolve(:retry_strategy)
+
+      # Decorate: Client -> Retry (no cache for uploads)
+      HTTP::RetryDecorator.new(client:, retry_strategy:)
+    end
+
+    # Register downloader
+    register(:downloader, memoize: false) do
+      Transfer::Downloader.new
+    end
+
+    # Register uploader
+    register(:uploader, memoize: true) do
+      Transfer::Uploader.new
+    end
+
+    # Register service credential
+    register(:service_credential, memoize: true) { ServiceCredential.load }
+
+    # Register MOD Portal API client
+    register(:mod_portal_api, memoize: true) do
+      API::MODPortalAPI.new
+    end
+
+    # Register MOD Download API client
+    register(:mod_download_api, memoize: false) do
+      API::MODDownloadAPI.new
+    end
+
+    # Register API credential (for MOD upload/management)
+    register(:api_credential, memoize: true) { APICredential.load }
+
+    # Register MOD Management API client
+    register(:mod_management_api, memoize: true) do
+      api = API::MODManagementAPI.new
+      # Subscribe mod_portal_api to invalidate cache when MOD is changed on portal
+      api.subscribe(resolve(:mod_portal_api))
+      api
+    end
+
+    # Register portal (high-level API wrapper)
+    register(:portal, memoize: false) do
+      Portal.new
+    end
+
+    # 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
+    setting :cache do
+      # Download cache settings (for MOD files)
+      setting :download do
+        setting :dir, constructor: ->(value) { Pathname(value) }
+        setting :ttl, default: nil # nil for unlimited (MOD files are immutable)
+        setting :max_file_size, default: nil # nil for unlimited
+        setting :compression_threshold, default: nil # nil for no compression (binary files)
+      end
+
+      # API cache settings (for API responses)
+      setting :api do
+        setting :dir, constructor: ->(value) { Pathname(value) }
+        setting :ttl, default: 3600 # 1 hour (API responses may change)
+        setting :max_file_size, default: 10 * 1024 * 1024 # 10MiB (JSON responses)
+        setting :compression_threshold, default: 0 # always compress (JSON is highly compressible)
+      end
+
+      # info.json cache settings (for MOD metadata from ZIP files)
+      setting :info_json do
+        setting :dir, constructor: ->(value) { Pathname(value) }
+        setting :ttl, default: nil # nil for unlimited (info.json is immutable within a MOD ZIP)
+        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
+    end
+
+    # Load configuration from file
+    #
+    # @param path [Pathname, String, 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
+        config_path = Pathname(path)
+        raise ConfigurationError, "Configuration file not found: #{config_path}" unless config_path.exist?
+      else
+        # Default path is optional
+        config_path = resolve(:runtime).factorix_config_path
+        return unless config_path.exist?
+      end
+
+      instance_eval(config_path.read, config_path.to_s)
+    end
+
+    runtime = resolve(:runtime)
+    config.cache.download.dir = runtime.factorix_cache_dir / "download"
+    config.cache.api.dir = runtime.factorix_cache_dir / "api"
+    config.cache.info_json.dir = runtime.factorix_cache_dir / "info_json"
+  end
+end

data/lib/factorix/cache/file_system.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "pathname"
+require "zlib"
+
+module Factorix
+  module Cache
+    # File system based cache storage implementation.
+    #
+    # Uses a two-level directory structure to store cached files,
+    # with file locking to handle concurrent access and TTL support
+    # for cache expiration.
+    class FileSystem
+      # @!parse
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      include Import[:logger]
+
+      # Maximum lifetime of lock files in seconds.
+      # Lock files older than this will be considered stale and removed
+      LOCK_FILE_LIFETIME = 3600 # 1 hour in seconds
+      public_constant :LOCK_FILE_LIFETIME
+
+      # zlib CMF byte indicating DEFLATE compression with default window size.
+      # Used to detect if cached data is zlib-compressed
+      ZLIB_CMF_BYTE = 0x78
+      private_constant :ZLIB_CMF_BYTE
+
+      # Initialize a new file system cache storage.
+      # Creates the cache directory if it doesn't exist
+      #
+      # @param cache_dir [Pathname] path to the cache directory
+      # @param ttl [Integer, nil] time-to-live in seconds (nil for unlimited)
+      # @param max_file_size [Integer, nil] maximum file size in bytes (nil for unlimited)
+      # @param compression_threshold [Integer, nil] compress data larger than this size in bytes
+      #   (nil: no compression, 0: always compress, N: compress if >= N bytes)
+      def initialize(cache_dir, ttl: nil, max_file_size: nil, compression_threshold: nil, logger: nil)
+        super(logger:)
+        @cache_dir = cache_dir
+        @ttl = ttl
+        @max_file_size = max_file_size
+        @compression_threshold = compression_threshold
+        @cache_dir.mkpath
+        logger.info("Initializing cache", dir: @cache_dir.to_s, ttl: @ttl, max_size: @max_file_size, compression_threshold: @compression_threshold)
+      end
+
+      # Generate a cache key for the given URL string.
+      # Uses SHA1 to create a unique, deterministic key
+      #
+      # @param url_string [String] URL string to generate key for
+      # @return [String] cache key
+      # Use Digest(:SHA1) instead of Digest::SHA1 for thread-safety (Ruby 2.2+)
+      def key_for(url_string) = Digest(:SHA1).hexdigest(url_string)
+
+      # Check if a cache entry exists and is not expired.
+      # A cache entry is considered to exist if its file exists and is not expired
+      #
+      # @param key [String] cache key to check
+      # @return [Boolean] true if the cache entry exists and is valid, false otherwise
+      def exist?(key)
+        return false unless cache_path_for(key).exist?
+        return true if @ttl.nil?
+
+        !expired?(key)
+      end
+
+      # Fetch a cached file and copy it to the output path.
+      # If the cache entry doesn't exist or is expired, returns false without modifying the output path.
+      # Automatically decompresses zlib-compressed cache entries.
+      #
+      # @param key [String] cache key to fetch
+      # @param output [Pathname] path to copy the cached file to
+      # @return [Boolean] true if the cache entry was found and copied, false otherwise
+      def fetch(key, output)
+        path = cache_path_for(key)
+        unless path.exist?
+          logger.debug("Cache miss", key:)
+          return false
+        end
+
+        if expired?(key)
+          logger.debug("Cache expired", key:, age_seconds: age(key))
+          return false
+        end
+
+        data = path.binread
+        if zlib_compressed?(data)
+          data = Zlib.inflate(data)
+          output.binwrite(data)
+        else
+          FileUtils.cp(path, output)
+        end
+        logger.debug("Cache hit", key:)
+        true
+      end
+
+      # Read a cached file as a string.
+      # If the cache entry doesn't exist or is expired, returns nil.
+      # Automatically decompresses zlib-compressed cache entries.
+      #
+      # @param key [String] cache key to read
+      # @param encoding [Encoding, String] encoding to use (default: ASCII-8BIT for binary)
+      # @return [String, nil] cached content or nil if not found/expired
+      def read(key, encoding: Encoding::ASCII_8BIT)
+        path = cache_path_for(key)
+        return nil unless path.exist?
+        return nil if expired?(key)
+
+        data = path.binread
+        data = Zlib.inflate(data) if zlib_compressed?(data)
+        data.force_encoding(encoding)
+      end
+
+      # Store a file in the cache.
+      # Creates necessary subdirectories and stores the file in the cache.
+      # Optionally compresses data based on compression_threshold setting.
+      # If the (possibly compressed) size exceeds max_file_size, skips caching and returns false.
+      #
+      # @param key [String] cache key to store under
+      # @param src [Pathname] path of the file to store
+      # @return [Boolean] true if cached successfully, false if skipped due to size limit
+      def store(key, src)
+        data = src.binread
+        original_size = data.bytesize
+
+        if should_compress?(original_size)
+          data = Zlib.deflate(data)
+          logger.debug("Compressed data", original_size:, compressed_size: data.bytesize)
+        end
+
+        if @max_file_size && data.bytesize > @max_file_size
+          logger.warn("File size exceeds cache limit, skipping", size_bytes: data.bytesize, limit_bytes: @max_file_size)
+          return false
+        end
+
+        path = cache_path_for(key)
+        path.dirname.mkpath
+        path.binwrite(data)
+        logger.debug("Stored in cache", key:, size_bytes: data.bytesize)
+        true
+      end
+
+      # Delete a specific cache entry.
+      #
+      # @param key [String] cache key to delete
+      # @return [Boolean] true if the entry was deleted, false if it didn't exist
+      def delete(key)
+        path = cache_path_for(key)
+        return false unless path.exist?
+
+        path.delete
+        logger.debug("Deleted from cache", key:)
+        true
+      end
+
+      # Clear all cache entries.
+      # Removes all files in the cache directory.
+      #
+      # @return [void]
+      def clear
+        logger.info("Clearing cache directory", dir: @cache_dir.to_s)
+        count = 0
+        @cache_dir.glob("**/*").each do |path|
+          if path.file?
+            path.delete
+            count += 1
+          end
+        end
+        logger.info("Cache cleared", files_removed: count)
+      end
+
+      # Get the age of a cache entry in seconds.
+      # Returns nil if the entry doesn't exist.
+      #
+      # @param key [String] cache key
+      # @return [Float, nil] age in seconds, or nil if entry doesn't exist
+      def age(key)
+        path = cache_path_for(key)
+        return nil unless path.exist?
+
+        Time.now - path.mtime
+      end
+
+      # Check if a cache entry has expired based on TTL.
+      # Returns false if TTL is not set (unlimited) or if entry doesn't exist.
+      #
+      # @param key [String] cache key
+      # @return [Boolean] true if expired, false otherwise
+      def expired?(key)
+        return false if @ttl.nil?
+
+        age_seconds = age(key)
+        return false if age_seconds.nil?
+
+        age_seconds > @ttl
+      end
+
+      # Get the size of a cached file in bytes.
+      # Returns nil if the entry doesn't exist or is expired.
+      #
+      # @param key [String] cache key
+      # @return [Integer, nil] file size in bytes, or nil if entry doesn't exist/expired
+      def size(key)
+        path = cache_path_for(key)
+        return nil unless path.exist?
+        return nil if expired?(key)
+
+        path.size
+      end
+
+      # Executes the given block with a file lock.
+      # Uses flock for process-safe file locking and automatically removes stale locks
+      #
+      # @param key [String] cache key to lock
+      # @yield Executes the block with exclusive file lock
+      # @return [void]
+      def with_lock(key)
+        lock_path = lock_path_for(key)
+        cleanup_stale_lock(lock_path)
+
+        lock_path.dirname.mkpath
+        lock_path.open(File::RDWR | File::CREAT) do |lock|
+          if lock.flock(File::LOCK_EX)
+            logger.debug("Acquired lock", key:)
+            begin
+              yield
+            ensure
+              lock.flock(File::LOCK_UN)
+              logger.debug("Released lock", key:)
+              begin
+                lock_path.unlink
+              rescue => e
+                logger.debug("Failed to remove lock file", path: lock_path.to_s, error: e.message)
+                nil
+              end
+            end
+          end
+        end
+      end
+
+      # Get the cache file path for the given key.
+      # Uses a two-level directory structure to avoid too many files in one directory
+      #
+      # @param key [String] cache key
+      # @return [Pathname] path to the cache file
+      private def cache_path_for(key)
+        prefix = key[0, 2]
+        @cache_dir.join(prefix, key[2..])
+      end
+
+      # Get the lock file path for the given key.
+      # Lock files are stored alongside cache files with a .lock extension
+      #
+      # @param key [String] cache key
+      # @return [Pathname] path to the lock file
+      private def lock_path_for(key)
+        cache_path_for(key).sub_ext(".lock")
+      end
+
+      # Check if data should be compressed based on compression_threshold setting.
+      #
+      # @param size [Integer] data size in bytes
+      # @return [Boolean] true if data should be compressed
+      private def should_compress?(size)
+        return false if @compression_threshold.nil?
+
+        size >= @compression_threshold
+      end
+
+      # Check if data is zlib-compressed by examining the CMF and FLG bytes.
+      # zlib header consists of CMF (byte 0) and FLG (byte 1) where
+      # (CMF * 256 + FLG) % 31 must equal 0.
+      #
+      # @param data [String] binary data to check
+      # @return [Boolean] true if data appears to be zlib-compressed
+      private def zlib_compressed?(data)
+        return false if data.bytesize < 2
+
+        cmf = data.getbyte(0)
+        flg = data.getbyte(1)
+        cmf == ZLIB_CMF_BYTE && ((cmf << 8) | flg) % 31 == 0
+      end
+
+      # Remove lock file if it exists and is older than LOCK_FILE_LIFETIME.
+      # This prevents orphaned locks from blocking the cache indefinitely
+      #
+      # @param lock_path [Pathname] path to the lock file
+      # @return [void]
+      private def cleanup_stale_lock(lock_path)
+        return unless lock_path.exist?
+
+        age = Time.now - lock_path.mtime
+        return if age <= LOCK_FILE_LIFETIME
+
+        begin
+          lock_path.unlink
+          logger.warn("Removed stale lock", path: lock_path.to_s, age_seconds: age)
+        rescue => e
+          logger.debug("Failed to remove stale lock", path: lock_path.to_s, error: e.message)
+          nil
+        end
+      end
+    end
+  end
+end