factorix 0.5.0

data/lib/factorix/game_version.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Factorix
+  GameVersion = Data.define(:major, :minor, :patch, :build)
+
+  # Represent a 4-component game version number (major.minor.patch-build)
+  #
+  # This class represents Factorio's game version format, which uses
+  # 64 bits (4 x 16-bit unsigned integers) to store version information.
+  #
+  # @see https://wiki.factorio.com/Version_string_format
+  class GameVersion
+    include Comparable
+
+    # @!attribute [r] major
+    #   @return [Integer] major version number (0-65535)
+    # @!attribute [r] minor
+    #   @return [Integer] minor version number (0-65535)
+    # @!attribute [r] patch
+    #   @return [Integer] patch version number (0-65535)
+    # @!attribute [r] build
+    #   @return [Integer] build version number (0-65535)
+
+    UINT16_MAX = (2**16) - 1
+    private_constant :UINT16_MAX
+
+    class << self
+      private def validate_component(value, name)
+        raise VersionParseError, "#{name} must be an Integer, got #{value.class}" unless value.is_a?(Integer)
+        return if value.between?(0, UINT16_MAX)
+
+        raise VersionParseError, "#{name} must be between 0 and #{UINT16_MAX}, got #{value}"
+      end
+    end
+
+    # Create GameVersion from version string "X.Y.Z-B" or "X.Y.Z"
+    #
+    # @param str [String] version string in "X.Y.Z-B" format (build defaults to 0 if omitted)
+    # @return [GameVersion]
+    # @raise [VersionParseError] if string format is invalid
+    def self.from_string(str)
+      unless /\A(\d+)\.(\d+)\.(\d+)(?:-(\d+))?\z/ =~ str
+        raise VersionParseError, "invalid version string: #{str.inspect}"
+      end
+
+      major = Integer($1)
+      minor = Integer($2)
+      patch = Integer($3)
+      build = $4.nil? ? 0 : Integer($4)
+
+      validate_component(major, :major)
+      validate_component(minor, :minor)
+      validate_component(patch, :patch)
+      validate_component(build, :build)
+
+      new(major:, minor:, patch:, build:)
+    end
+
+    # Create GameVersion from four integers
+    #
+    # @param major [Integer] major version number (0-65535)
+    # @param minor [Integer] minor version number (0-65535)
+    # @param patch [Integer] patch version number (0-65535)
+    # @param build [Integer] build version number (0-65535, defaults to 0)
+    # @return [GameVersion]
+    # @raise [VersionParseError] if any component is out of range
+    def self.from_numbers(major, minor, patch, build=0)
+      validate_component(major, :major)
+      validate_component(minor, :minor)
+      validate_component(patch, :patch)
+      validate_component(build, :build)
+
+      new(major:, minor:, patch:, build:)
+    end
+
+    private_class_method :new, :[]
+
+    # Convert to string representation
+    #
+    # @return [String] Version string in format "X.Y.Z-B" or "X.Y.Z" if build is 0
+    def to_s = build.zero? ? "#{major}.#{minor}.#{patch}" : "#{major}.#{minor}.#{patch}-#{build}"
+
+    # Convert to array of integers
+    #
+    # @return [Array<Integer>] Array containing [major, minor, patch, build]
+    def to_a = [major, minor, patch, build].freeze
+
+    # Compare with another GameVersion
+    #
+    # @param other [GameVersion] Version to compare with
+    # @return [Integer, nil] -1, 0, 1 for less than, equal to, greater than; nil if not comparable
+    def <=>(other)
+      return nil unless other.is_a?(GameVersion)
+
+      to_a <=> other.to_a
+    end
+  end
+end

data/lib/factorix/http/cache_decorator.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "dry/events"
+require "pathname"
+require "tempfile"
+
+module Factorix
+  module HTTP
+    # Adds caching for GET requests
+    #
+    # Stores successful GET responses in FileSystem cache.
+    # Only caches non-streaming requests (no block given).
+    class CacheDecorator
+      # @!parse
+      #   # @return [HTTP::Client]
+      #   attr_reader :client
+      #   # @return [Cache::FileSystem]
+      #   attr_reader :cache
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      include Import[:client, :cache, :logger]
+      include Dry::Events::Publisher[:http]
+
+      register_event("cache.hit")
+      register_event("cache.miss")
+
+      # Execute an HTTP request (only caches GET without block)
+      #
+      # @param method [Symbol] HTTP method
+      # @param uri [URI::HTTPS] target URI
+      # @param headers [Hash<String, String>] request headers
+      # @param body [String, IO, nil] request body
+      # @yield [Net::HTTPResponse] for streaming responses
+      # @return [Response, Object] response object or parsed data
+      def request(method, uri, headers: {}, body: nil, &block)
+        if method == :get && !block
+          get(uri, headers:)
+        else
+          client.request(method, uri, headers:, body:, &block)
+        end
+      end
+
+      # Execute a GET request with caching
+      #
+      # @param uri [URI::HTTPS] target URI
+      # @param headers [Hash<String, String>] request headers
+      # @yield [Net::HTTPResponse] for streaming responses
+      # @return [Response, Object] response object or parsed data
+      def get(uri, headers: {}, &block)
+        # Don't cache streaming requests
+        return client.get(uri, headers:, &block) if block
+
+        key = cache.key_for(uri.to_s)
+
+        cached_body = cache.read(key)
+        if cached_body
+          logger.debug("Cache hit", uri: uri.to_s)
+          publish("cache.hit", url: uri.to_s)
+          return CachedResponse.new(cached_body)
+        end
+
+        logger.debug("Cache miss", uri: uri.to_s)
+        publish("cache.miss", url: uri.to_s)
+
+        # Locking prevents concurrent downloads of the same resource
+        cache.with_lock(key) do
+          # Double-check: another thread might have filled the cache
+          cached_body = cache.read(key)
+          if cached_body
+            publish("cache.hit", url: uri.to_s)
+            return CachedResponse.new(cached_body)
+          end
+
+          response = client.get(uri, headers:)
+
+          if response.success?
+            with_temporary_file do |temp|
+              temp.write(response.body)
+              temp.close
+              cache.store(key, Pathname(temp.path))
+            end
+          end
+
+          response
+        end
+      end
+
+      # Execute a POST request (never cached)
+      #
+      # @param uri [URI::HTTPS] target URI
+      # @param body [String, IO] request body
+      # @param headers [Hash<String, String>] request headers
+      # @param content_type [String, nil] Content-Type header
+      # @return [Response] response object
+      def post(uri, body:, headers: {}, content_type: nil) = client.post(uri, body:, headers:, content_type:)
+
+      private def with_temporary_file
+        temp_file = Tempfile.new("http_cache")
+        yield temp_file
+      ensure
+        temp_file&.close
+        temp_file&.unlink
+      end
+    end
+  end
+end

data/lib/factorix/http/cached_response.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Factorix
+  module HTTP
+    # Response wrapper for cached data
+    #
+    # Provides a simple response object that can be constructed from
+    # a cached body string, without requiring an actual HTTP response.
+    # Used by CacheDecorator to return cached content with a uniform
+    # interface matching Response objects.
+    class CachedResponse
+      attr_reader :body
+      attr_reader :code
+      attr_reader :headers
+
+      # @param body [String] cached response body
+      def initialize(body)
+        @body = body
+        @code = 200
+        @headers = {"content-type" => ["application/octet-stream"]}
+      end
+
+      # Always returns true for cached responses
+      #
+      # Since only successful responses are cached, all CachedResponse
+      # objects represent successful HTTP interactions.
+      #
+      # @return [Boolean] true
+      def success? = true
+
+      # Get content length from body size
+      #
+      # @return [Integer] body size in bytes
+      def content_length = @body.bytesize
+    end
+  end
+end

data/lib/factorix/http/client.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module Factorix
+  module HTTP
+    # Low-level HTTP client using Net::HTTP
+    #
+    # Responsibilities:
+    # - Create and configure Net::HTTP instances
+    # - Execute HTTP methods (GET, POST)
+    # - Handle redirects (up to MAX_REDIRECTS)
+    # - Parse response codes and raise appropriate errors
+    # - Stream reading/writing for large files
+    class Client
+      include Import[:logger]
+
+      MAX_REDIRECTS = 10
+      private_constant :MAX_REDIRECTS
+
+      # @return [Array<String>] URL parameter names to mask in logs
+      attr_reader :masked_params
+
+      # @param masked_params [Array<String>] URL parameter names to mask in logs
+      def initialize(masked_params: [], **)
+        super(**)
+        @masked_params = masked_params.freeze
+      end
+
+      # Execute an HTTP request
+      #
+      # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+      # @param uri [URI::HTTPS] target URI
+      # @param headers [Hash<String, String>] request headers
+      # @param body [String, IO, nil] request body
+      # @yield [Net::HTTPResponse] for streaming responses
+      # @return [Response] response object
+      # @raise [URLError] if URI is not HTTPS or too many redirects
+      # @raise [InvalidArgumentError] if HTTP method is unsupported
+      # @raise [HTTPNotFoundError] for 404 errors
+      # @raise [HTTPClientError] for 4xx errors
+      # @raise [HTTPServerError] for 5xx errors
+      # @raise [HTTPError] for other HTTP errors
+      def request(method, uri, headers: {}, body: nil, &)
+        raise URLError, "URL must be HTTPS" unless uri.is_a?(URI::HTTPS)
+
+        logger.info("HTTP request", method: method.upcase, url: mask_credentials(uri))
+        perform_request(method, uri, redirect_count: 0, headers:, body:, &)
+      end
+
+      # Execute a GET request
+      #
+      # @param uri [URI::HTTPS] target URI
+      # @param headers [Hash<String, String>] request headers
+      # @yield [Net::HTTPResponse] for streaming responses
+      # @return [Response] response object
+      def get(uri, headers: {}, &) = request(:get, uri, headers:, &)
+
+      # Execute a POST request
+      #
+      # @param uri [URI::HTTPS] target URI
+      # @param body [String, IO] request body
+      # @param headers [Hash<String, String>] request headers
+      # @param content_type [String, nil] Content-Type header
+      # @return [Response] response object
+      def post(uri, body:, headers: {}, content_type: nil)
+        headers = headers.merge("Content-Type" => content_type) if content_type
+        request(:post, uri, body:, headers:)
+      end
+
+      private def perform_request(method, uri, redirect_count:, headers:, body:, &block)
+        if redirect_count > MAX_REDIRECTS
+          logger.error("Too many redirects", redirect_count:)
+          raise URLError, "Too many redirects (#{redirect_count})"
+        end
+
+        http = create_http(uri)
+        req = build_request(method, uri, headers:, body:)
+
+        result = nil
+        http.request(req) do |response|
+          result = handle_response(response, method, uri, redirect_count, &block)
+        end
+        result
+      end
+
+      private def handle_response(response, _method, _uri, redirect_count, &block)
+        case response
+        when Net::HTTPSuccess, Net::HTTPPartialContent
+          yield(response) if block
+          Response.new(response)
+
+        when Net::HTTPRedirection
+          location = response["Location"]
+          redirect_url = URI(location)
+          logger.info("Following redirect", location: mask_credentials(redirect_url))
+
+          perform_request(:get, redirect_url, redirect_count: redirect_count + 1, headers: {}, body: nil, &block)
+
+        when Net::HTTPNotFound
+          api_error, api_message = parse_api_error(response)
+          logger.error("HTTP not found", code: response.code, message: response.message, api_message:)
+          raise HTTPNotFoundError.new("#{response.code} #{response.message}", api_error:, api_message:)
+
+        when Net::HTTPClientError
+          api_error, api_message = parse_api_error(response)
+          logger.error("HTTP client error", code: response.code, message: response.message, api_message:)
+          raise HTTPClientError.new("#{response.code} #{response.message}", api_error:, api_message:)
+
+        when Net::HTTPServerError
+          logger.error("HTTP server error", code: response.code, message: response.message)
+          raise HTTPServerError, "#{response.code} #{response.message}"
+
+        else
+          raise HTTPError, "#{response.code} #{response.message}"
+        end
+      rescue URI::InvalidURIError
+        raise HTTPError, "Invalid redirect URI: #{response["Location"]}"
+      end
+
+      # Parse API error response body for error and message fields
+      #
+      # @param response [Net::HTTPResponse] HTTP response
+      # @return [Array(String, String), Array(nil, nil)] tuple of [api_error, api_message]
+      private def parse_api_error(response)
+        return [nil, nil] unless response.content_type&.include?("application/json")
+
+        body = response.body
+        return [nil, nil] if body.nil? || body.empty?
+
+        json = JSON.parse(body, symbolize_names: true)
+        [json[:error], json[:message]]
+      rescue JSON::ParserError
+        [nil, nil]
+      end
+
+      private def build_request(method, uri, headers:, body:)
+        request = case method
+                  when :get then Net::HTTP::Get.new(uri)
+                  when :post then Net::HTTP::Post.new(uri)
+                  when :put then Net::HTTP::Put.new(uri)
+                  when :delete then Net::HTTP::Delete.new(uri)
+                  else raise InvalidArgumentError, "Unsupported method: #{method}"
+                  end
+
+        headers.each {|k, v| request[k] = v }
+
+        if body
+          if body.respond_to?(:read)
+            request.body_stream = body
+          else
+            request.body = body
+          end
+        end
+
+        request
+      end
+
+      private def create_http(uri)
+        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=)
+        end
+      end
+
+      # Mask sensitive URL parameters for logging
+      #
+      # @param url [URI] URL to mask
+      # @return [String] URL string with sensitive parameters masked
+      private def mask_credentials(url)
+        return url.to_s unless url.query
+        return url.to_s if masked_params.empty?
+
+        masked_url = url.dup
+        params = URI.decode_www_form(masked_url.query).to_h
+        masked_params.each {|key| params[key] = "*****" if params.key?(key) }
+        masked_url.query = URI.encode_www_form(params)
+        masked_url.to_s
+      end
+    end
+  end
+end

data/lib/factorix/http/response.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Factorix
+  module HTTP
+    # Simple response wrapper for Net::HTTP responses
+    class Response
+      attr_reader :code
+      attr_reader :body
+      attr_reader :headers
+      attr_reader :raw_response
+
+      # @param net_http_response [Net::HTTPResponse] Raw Net::HTTP response
+      def initialize(net_http_response)
+        @code = Integer(net_http_response.code, 10)
+        @body = net_http_response.body
+        @headers = net_http_response.to_hash
+        @raw_response = net_http_response
+      end
+
+      # Check if response is successful (2xx)
+      #
+      # @return [Boolean] true if 2xx response
+      def success? = (200..299).cover?(@code)
+
+      # Get Content-Length from headers
+      #
+      # @return [Integer, nil] content length in bytes, or nil if not present
+      def content_length = Integer(@headers["content-length"]&.first, 10)
+    end
+  end
+end

data/lib/factorix/http/retry_decorator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Factorix
+  module HTTP
+    # Adds automatic retry with exponential backoff to HTTP client
+    #
+    # Wraps any HTTP client and retries requests on network errors
+    # using the configured RetryStrategy.
+    class RetryDecorator
+      # @!parse
+      #   # @return [HTTP::Client]
+      #   attr_reader :client
+      #   # @return [HTTP::RetryStrategy]
+      #   attr_reader :retry_strategy
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      include Import[:client, :retry_strategy, :logger]
+
+      # Execute an HTTP request with retry
+      #
+      # @param method [Symbol] HTTP method
+      # @param uri [URI::HTTPS] target URI
+      # @param headers [Hash<String, String>] request headers
+      # @param body [String, IO, nil] request body
+      # @yield [Net::HTTPResponse] for streaming responses
+      # @return [Response] response object
+      def request(method, uri, headers: {}, body: nil, &block)
+        retry_strategy.with_retry do
+          client.request(method, uri, headers:, body:, &block)
+        end
+      end
+
+      # Execute a GET request with retry
+      #
+      # @param uri [URI::HTTPS] target URI
+      # @param headers [Hash<String, String>] request headers
+      # @yield [Net::HTTPResponse] for streaming responses
+      # @return [Response] response object
+      def get(uri, headers: {}, &block)
+        retry_strategy.with_retry do
+          client.get(uri, headers:, &block)
+        end
+      end
+
+      # Execute a POST request with retry
+      #
+      # @param uri [URI::HTTPS] target URI
+      # @param body [String, IO] request body
+      # @param headers [Hash<String, String>] request headers
+      # @param content_type [String, nil] Content-Type header
+      # @return [Response] response object
+      def post(uri, body:, headers: {}, content_type: nil)
+        retry_strategy.with_retry do
+          client.post(uri, body:, headers:, content_type:)
+        end
+      end
+    end
+  end
+end

data/lib/factorix/http/retry_strategy.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "net/protocol"
+require "openssl"
+require "retriable"
+
+module Factorix
+  module HTTP
+    # Class that manages retry strategy with exponential backoff and randomization
+    class RetryStrategy
+      # @!parse
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      include Import[:logger]
+
+      DEFAULT_OPTIONS = {
+        tries: 3,                 # Number of attempts (including the initial try)
+        base_interval: 1.0,       # Start with 1 second
+        multiplier: 2.0,          # Double the interval each time
+        rand_factor: 0.25,        # Add randomization
+        on: [                     # Exceptions to retry on
+          Errno::ETIMEDOUT,
+          Errno::ECONNRESET,
+          Errno::ECONNREFUSED,
+          Net::OpenTimeout,
+          Net::ReadTimeout,
+          SocketError,
+          OpenSSL::SSL::SSLError,
+          EOFError
+        ]
+      }.freeze
+      private_constant :DEFAULT_OPTIONS
+
+      # Initialize a new retry strategy with customizable options
+      #
+      # @param options [Hash] Options for retry behavior
+      # @option options [Integer] :tries Number of attempts (including the initial try)
+      # @option options [Float] :base_interval Initial interval between retries (seconds)
+      # @option options [Float] :multiplier Exponential backoff multiplier
+      # @option options [Float] :rand_factor Randomization factor
+      # @option options [Array<Class>] :on Exception classes to retry on
+      # @option options [Proc] :on_retry Callback called on each retry
+      def initialize(logger: nil, **options)
+        super(logger:)
+        @options = configure_options(options)
+      end
+
+      # Execute the block with automatic retry on specified exceptions.
+      # Uses exponential backoff with randomization for retry intervals
+      #
+      # @yield Block to execute
+      # @return [Object] Return value of the block
+      # @raise [StandardError] If the block fails after all retries
+      def with_retry(&) = Retriable.retriable(**@options, &)
+
+      # Configure retry options by merging with defaults and setting up callbacks
+      #
+      # @param options [Hash] User-provided options to merge with defaults
+      # @return [Hash] Complete set of configured options
+      private def configure_options(options)
+        result = DEFAULT_OPTIONS.merge(options)
+        unless result.key?(:on_retry)
+          result[:on_retry] = method(:default_retry_callback).to_proc
+        end
+        result
+      end
+
+      # Default callback for retry attempts that logs retry information
+      #
+      # @param exception [StandardError] The exception that triggered the retry
+      # @param try [Integer] The current retry attempt number
+      # @param elapsed_time [Float] Time elapsed since first attempt
+      # @param next_interval [Float] Time until next retry attempt
+      # @return [void]
+      private def default_retry_callback(exception, try, elapsed_time, next_interval)
+        logger.warn "Retry #{try} after #{elapsed_time}s, next in #{next_interval}s: #{exception.class} - #{exception.message}"
+      end
+    end
+  end
+end

data/lib/factorix/info_json.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+require "tempfile"
+require "zip"
+
+module Factorix
+  InfoJSON = Data.define(:name, :version, :title, :author, :description, :factorio_version, :dependencies)
+
+  # Factorio MOD info.json representation
+  #
+  # Represents the metadata file that must be present in every Factorio MOD.
+  # Only required fields (name, version, title, author) are enforced.
+  #
+  # @see https://lua-api.factorio.com/latest/auxiliary/mod-structure.html
+  class InfoJSON
+    # Parse info.json from JSON string
+    #
+    # @param json_string [String] JSON content
+    # @return [InfoJSON] parsed info.json
+    # @raise [FileFormatError] if required fields are missing or JSON is invalid
+    def self.from_json(json_string)
+      data = JSON.parse(json_string)
+
+      required_fields = %w[name version title author]
+      missing = required_fields - data.keys
+      raise FileFormatError, "Missing required fields: #{missing.join(", ")}" unless missing.empty?
+
+      parser = Dependency::Parser.new
+      dependencies = (data["dependencies"] || []).map {|dep_str| parser.parse(dep_str) }
+
+      new(name: data["name"], version: MODVersion.from_string(data["version"]), title: data["title"], author: data["author"], description: data["description"] || "", factorio_version: data["factorio_version"], dependencies:)
+    rescue JSON::ParserError => e
+      raise FileFormatError, "Invalid JSON: #{e.message}"
+    rescue VersionParseError, DependencyParseError => e
+      raise FileFormatError, e.message
+    end
+
+    # Extract from zip file
+    #
+    # Uses caching to avoid repeated ZIP extraction for the same file.
+    # Cache key is based on file path (MOD ZIPs are immutable after download).
+    # Uses double-checked locking to prevent concurrent extraction while
+    # avoiding lock overhead on cache hits.
+    #
+    # @param zip_path [Pathname] path to MOD zip file
+    # @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)
+
+      if (cached_json = cache.read(cache_key, encoding: Encoding::UTF_8))
+        logger.debug("info.json cache hit", path: zip_path.to_s)
+        return from_json(cached_json)
+      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))
+          logger.debug("info.json cache hit (after lock)", path: zip_path.to_s)
+          return from_json(cached_json)
+        end
+
+        json_string = Zip::File.open(zip_path) {|zip_file|
+          info_entry = zip_file.find {|entry| entry.name.end_with?("/info.json") }
+          raise FileFormatError, "info.json not found in #{zip_path}" unless info_entry
+
+          info_entry.get_input_stream.read
+        }
+
+        temp_file = Tempfile.new("info_json_cache")
+        begin
+          temp_file.write(json_string)
+          temp_file.close
+          cache.store(cache_key, Pathname(temp_file.path))
+          logger.debug("Stored info.json in cache", path: zip_path.to_s)
+        ensure
+          temp_file.unlink
+        end
+
+        from_json(json_string)
+      end
+    rescue Zip::Error => e
+      raise FileFormatError, "Invalid zip file: #{e.message}"
+    end
+  end
+end