factorix 0.5.0

data/lib/factorix/ser_des/serializer.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Factorix
+  module SerDes
+    # Serialize data to binary format
+    #
+    # This class provides methods to serialize various data types to Factorio's
+    # binary file format, following the specifications documented in the Factorio wiki.
+    class Serializer
+      # @!parse
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      include Import[:logger]
+
+      # Create a new Serializer instance
+      #
+      # @param stream [IO] An IO-like object that responds to #write
+      # @param logger [Dry::Logger::Dispatcher] optional logger
+      # @raise [ArgumentError] If the stream doesn't respond to #write
+      def initialize(stream, logger: nil)
+        super(logger:)
+        raise ArgumentError, "can't write to the given argument" unless stream.respond_to?(:write)
+
+        @stream = stream
+        logger.debug "Initializing Serializer"
+      end
+
+      # Write raw bytes to the stream
+      #
+      # @param data [String] Binary data to write
+      # @raise [ArgumentError] If data is nil
+      # @return [void]
+      def write_bytes(data)
+        raise ArgumentError if data.nil?
+        return if data.empty?
+
+        @stream.write(data)
+      end
+
+      # Write an unsigned 8-bit integer
+      #
+      # @param uint8 [Integer] 8-bit unsigned integer
+      # @return [void]
+      def write_u8(uint8) = write_bytes([uint8].pack("C"))
+
+      # Write an unsigned 16-bit integer
+      #
+      # @param uint16 [Integer] 16-bit unsigned integer
+      # @return [void]
+      def write_u16(uint16) = write_bytes([uint16].pack("v"))
+
+      # Write an unsigned 32-bit integer
+      #
+      # @param uint32 [Integer] 32-bit unsigned integer
+      # @return [void]
+      def write_u32(uint32) = write_bytes([uint32].pack("V"))
+
+      # Write a space-optimized 16-bit unsigned integer
+      #
+      # @see https://wiki.factorio.com/Data_types#Space_Optimized
+      # @param uint16 [Integer] 16-bit unsigned integer
+      # @return [void]
+      def write_optim_u16(uint16)
+        if uint16 < 0xFF
+          write_u8(uint16 & 0xFF)
+        else
+          write_u8(0xFF)
+          write_u16(uint16)
+        end
+      end
+
+      # Write a space-optimized 32-bit unsigned integer
+      #
+      # @see https://wiki.factorio.com/Data_types#Space_Optimized
+      # @param uint32 [Integer] 32-bit unsigned integer
+      # @return [void]
+      def write_optim_u32(uint32)
+        if uint32 < 0xFF
+          write_u8(uint32 & 0xFF)
+        else
+          write_u8(0xFF)
+          write_u32(uint32)
+        end
+      end
+
+      # Write a boolean value
+      #
+      # @param bool [Boolean] Boolean value
+      # @return [void]
+      def write_bool(bool) = write_u8(bool ? 0x01 : 0x00)
+
+      # Write a string
+      #
+      # @param str [String] String to write (must be UTF-8 encoded)
+      # @raise [ArgumentError] If the string is not UTF-8 encoded
+      # @return [void]
+      def write_str(str)
+        if str.encoding != Encoding::UTF_8 && !(str.encoding == Encoding::ASCII_8BIT && str.force_encoding(Encoding::UTF_8).valid_encoding?)
+          logger.debug("String encoding error", expected: "UTF-8", got: str.encoding.name)
+          raise ArgumentError, "String must be UTF-8 encoded, got #{str.encoding}"
+        end
+
+        write_optim_u32(str.bytesize)
+        write_bytes(str.b)
+      end
+
+      # Write a string property
+      #
+      # @see https://wiki.factorio.com/Property_tree#String
+      # @param str [String] String to write
+      # @return [void]
+      def write_str_property(str)
+        if str.empty?
+          write_bool(true)
+        else
+          write_bool(false)
+          write_str(str)
+        end
+      end
+
+      # Write a double-precision floating point number
+      #
+      # @see https://wiki.factorio.com/Property_tree#Number
+      # @param dbl [Float] Double-precision floating point number
+      # @return [void]
+      def write_double(dbl) = write_bytes([dbl].pack("d"))
+
+      # Write a GameVersion object
+      #
+      # @param game_version [GameVersion] GameVersion object
+      # @return [void]
+      def write_game_version(game_version) = game_version.to_a.each {|u16| write_u16(u16) }
+
+      # Write a MODVersion object
+      #
+      # @param mod_version [MODVersion] MODVersion object
+      # @return [void]
+      def write_mod_version(mod_version) = mod_version.to_a.each {|u16| write_optim_u16(u16) }
+
+      # Write a list
+      #
+      # @see https://wiki.factorio.com/Property_tree#List
+      # @param list [Array] List of objects
+      # @return [void]
+      def write_list(list)
+        logger.debug("Writing list", size: list.size)
+        write_optim_u32(list.size)
+        list.each {|e| write_property_tree(e) }
+      end
+
+      # Write a dictionary
+      #
+      # @see https://wiki.factorio.com/Property_tree#Dictionary
+      # @param dict [Hash] Dictionary of key-value pairs
+      # @return [void]
+      def write_dictionary(dict)
+        logger.debug("Writing dictionary", size: dict.size)
+        write_u32(dict.size)
+        dict.each do |(key, value)|
+          write_str_property(key)
+          write_property_tree(value)
+        end
+      end
+
+      # Write a signed long integer (8 bytes)
+      #
+      # @param long [Integer] Signed long integer
+      # @return [void]
+      def write_long(long) = write_bytes([long].pack("q<"))
+
+      # Write an unsigned long integer (8 bytes)
+      #
+      # @param ulong [Integer] Unsigned long integer
+      # @return [void]
+      def write_unsigned_long(ulong) = write_bytes([ulong].pack("Q<"))
+
+      # Write a property tree
+      #
+      # @param obj [Object] Object to write
+      # @raise [Factorix::UnknownPropertyType] If the object type is not supported
+      # @return [void]
+      def write_property_tree(obj)
+        logger.debug("Writing property tree", type: obj.class.name)
+        case obj
+        when nil
+          # Type 0 - None (null value)
+          write_u8(0)
+          write_bool(false)
+        when true, false
+          # Type 1 - Boolean
+          write_u8(1)
+          write_bool(false)
+          write_bool(obj)
+        when Float
+          # Type 2 - Number (double)
+          write_u8(2)
+          write_bool(false)
+          write_double(obj)
+        when String
+          # Type 3 - String
+          write_u8(3)
+          write_bool(false)
+          write_str_property(obj)
+        when Array
+          # Type 4 - List
+          write_u8(4)
+          write_bool(false)
+          write_list(obj)
+        when Hash
+          # Type 5 - Dictionary
+          write_u8(5)
+          write_bool(false)
+          write_dictionary(obj)
+        when SignedInteger
+          # Type 6 - Signed integer
+          write_u8(6)
+          write_bool(false)
+          write_long(obj.__getobj__)
+        when UnsignedInteger
+          # Type 7 - Unsigned integer
+          write_u8(7)
+          write_bool(false)
+          write_unsigned_long(obj.__getobj__)
+        else
+          logger.debug("Unknown property type", type: obj.class.name)
+          raise UnknownPropertyType, "Unknown property type: #{obj.class}"
+        end
+      end
+    end
+  end
+end

data/lib/factorix/ser_des/signed_integer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Factorix
+  module SerDes
+    # Signed integer wrapper
+    #
+    # This class wraps an Integer value to indicate it was originally stored
+    # as a signed integer (Type 6) in Factorio's Property Tree format.
+    #
+    # @example Creating a signed integer
+    #   value = SignedInteger.new(42)
+    #   value + 1  # => 43 (behaves like Integer)
+    #
+    # @example Negative values are allowed
+    #   value = SignedInteger.new(-5)
+    class SignedInteger < SimpleDelegator
+      # Create a new SignedInteger
+      #
+      # @param value [Integer] The integer value
+      # @raise [ArgumentError] If value is not an Integer
+      def initialize(value)
+        raise ArgumentError, "value must be an Integer" unless value.is_a?(Integer)
+
+        super
+      end
+
+      # Get the underlying integer value
+      #
+      # @return [Integer] The wrapped integer value
+      def value = __getobj__
+
+      # Compare with another SignedInteger or Integer
+      #
+      # @param other [SignedInteger, Integer] The value to compare with
+      # @return [Boolean] True if equal
+      def ==(other)
+        case other
+        when SignedInteger
+          value == other.value
+        when Integer
+          value == other
+        else
+          false
+        end
+      end
+
+      # Hash code for use in Hash keys
+      #
+      # @return [Integer] Hash code
+      def hash = [value, :signed].hash
+
+      # Check if equal (alias for ==)
+      alias eql? ==
+
+      # String representation
+      #
+      # @return [String] String representation
+      def inspect = "#<Factorix::SerDes::SignedInteger:0x%016x value=#{value}>" % object_id
+    end
+  end
+end

data/lib/factorix/ser_des/unsigned_integer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Factorix
+  module SerDes
+    # Unsigned integer wrapper
+    #
+    # This class wraps a non-negative Integer value to indicate it was originally
+    # stored as an unsigned integer (Type 7) in Factorio's Property Tree format.
+    #
+    # @example Creating an unsigned integer
+    #   value = UnsignedInteger.new(42)
+    #   value + 1  # => 43 (behaves like Integer)
+    #
+    # @example Negative values raise an error
+    #   UnsignedInteger.new(-5)  # => ArgumentError
+    class UnsignedInteger < SimpleDelegator
+      # Create a new UnsignedInteger
+      #
+      # @param value [Integer] The integer value (must be non-negative)
+      # @raise [ArgumentError] If value is not an Integer
+      # @raise [ArgumentError] If value is negative
+      def initialize(value)
+        raise ArgumentError, "value must be an Integer" unless value.is_a?(Integer)
+        raise ArgumentError, "value must be non-negative" if value.negative?
+
+        super
+      end
+
+      # Get the underlying integer value
+      #
+      # @return [Integer] The wrapped integer value
+      def value = __getobj__
+
+      # Compare with another UnsignedInteger or Integer
+      #
+      # @param other [UnsignedInteger, Integer] The value to compare with
+      # @return [Boolean] True if equal
+      def ==(other)
+        case other
+        when UnsignedInteger
+          value == other.value
+        when Integer
+          value == other
+        else
+          false
+        end
+      end
+
+      # Hash code for use in Hash keys
+      #
+      # @return [Integer] Hash code
+      def hash = [value, :unsigned].hash
+
+      # Check if equal (alias for ==)
+      alias eql? ==
+
+      # String representation
+      #
+      # @return [String] String representation
+      def inspect = "#<Factorix::SerDes::UnsignedInteger:0x%016x value=#{value}>" % object_id
+    end
+  end
+end

data/lib/factorix/service_credential.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Factorix
+  ServiceCredential = Data.define(:username, :token)
+
+  # Service credentials for Factorio MOD downloads
+  #
+  # @see https://wiki.factorio.com/Mod_portal_API
+  class ServiceCredential
+    # @!attribute [r] username
+    #   @return [String] Factorio service username
+    # @!attribute [r] token
+    #   @return [String] Factorio service token
+
+    # Environment variable name for username
+    ENV_USERNAME = "FACTORIO_USERNAME"
+    private_constant :ENV_USERNAME
+
+    # Environment variable name for token
+    ENV_TOKEN = "FACTORIO_TOKEN"
+    private_constant :ENV_TOKEN
+
+    # Load service credentials with automatic source detection
+    #
+    # Tries environment variables first, falls back to player-data.json.
+    # Raises an error if only one environment variable is set (partial configuration).
+    #
+    # @return [ServiceCredential] new instance with credentials
+    # @raise [CredentialError] if only one of FACTORIO_USERNAME/FACTORIO_TOKEN is set
+    # @raise [CredentialError] if credentials are invalid or missing
+    def self.load
+      username_env = ENV.fetch(ENV_USERNAME, nil)
+      token_env = ENV.fetch(ENV_TOKEN, nil)
+
+      if username_env && token_env
+        from_env
+      elsif username_env || token_env
+        raise CredentialError, "Both #{ENV_USERNAME} and #{ENV_TOKEN} must be set (or neither)"
+      else
+        runtime = Application[:runtime]
+        from_player_data(runtime:)
+      end
+    end
+
+    # Create a new ServiceCredential instance from environment variables
+    #
+    # @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.debug "Loading service credentials from environment"
+
+      username = ENV.fetch(ENV_USERNAME, nil)
+      token = ENV.fetch(ENV_TOKEN, nil)
+
+      if username.nil?
+        logger.error("Failed to load service credentials", reason: "#{ENV_USERNAME} not set")
+        raise CredentialError, "#{ENV_USERNAME} environment variable is not set"
+      end
+      if username.empty?
+        logger.error("Failed to load service credentials", reason: "#{ENV_USERNAME} is empty")
+        raise CredentialError, "#{ENV_USERNAME} environment variable is empty"
+      end
+      if token.nil?
+        logger.error("Failed to load service credentials", reason: "#{ENV_TOKEN} not set")
+        raise CredentialError, "#{ENV_TOKEN} environment variable is not set"
+      end
+      if token.empty?
+        logger.error("Failed to load service credentials", reason: "#{ENV_TOKEN} is empty")
+        raise CredentialError, "#{ENV_TOKEN} environment variable is empty"
+      end
+
+      logger.info("Service credentials loaded successfully")
+      new(username:, token:)
+    end
+
+    # Create a new ServiceCredential instance from player-data.json
+    #
+    # @param runtime [Factorix::Runtime::Base] runtime instance
+    # @return [ServiceCredential] new instance with credentials from player-data.json
+    # @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.debug "Loading service credentials from player-data.json"
+
+      player_data_path = runtime.player_data_path
+      data = JSON.parse(player_data_path.read)
+
+      username = data["service-username"]
+      token = data["service-token"]
+
+      if username.nil?
+        logger.error("Failed to load credentials from player-data.json", reason: "service-username missing")
+        raise CredentialError, "service-username is missing in player-data.json"
+      end
+      if username.empty?
+        logger.error("Failed to load credentials from player-data.json", reason: "service-username empty")
+        raise CredentialError, "service-username is empty in player-data.json"
+      end
+      if token.nil?
+        logger.error("Failed to load credentials from player-data.json", reason: "service-token missing")
+        raise CredentialError, "service-token is missing in player-data.json"
+      end
+      if token.empty?
+        logger.error("Failed to load credentials from player-data.json", reason: "service-token empty")
+        raise CredentialError, "service-token is empty in player-data.json"
+      end
+
+      logger.info("Service credentials loaded from player-data.json")
+      new(username:, token:)
+    end
+
+    private_class_method :new, :[], :from_env, :from_player_data
+
+    # @return [String] string representation with masked credentials
+    def inspect = %[#<#{self.class} username="*****" token="*****">]
+
+    alias to_s inspect
+
+    # @param pp [PP] pretty printer
+    # @return [void]
+    def pretty_print(pp) = pp.text(inspect)
+  end
+end

data/lib/factorix/transfer/downloader.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "dry/events"
+require "pathname"
+require "tmpdir"
+require "uri"
+
+module Factorix
+  module Transfer
+    # File downloader with caching and progress tracking
+    #
+    # Downloads files from HTTPS URLs with automatic caching.
+    # Uses file locking to prevent concurrent downloads of the same file.
+    # HTTP redirects are handled automatically by the HTTP layer.
+    # Publishes progress events during download.
+    class Downloader
+      # @!parse
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      #   # @return [Cache::FileSystem]
+      #   attr_reader :cache
+      #   # @return [HTTP::Client]
+      #   attr_reader :client
+      include Import[:logger, cache: :download_cache, client: :download_http_client]
+      include Dry::Events::Publisher[:downloader]
+
+      register_event("download.started")
+      register_event("download.progress")
+      register_event("download.completed")
+      register_event("cache.hit")
+      register_event("cache.miss")
+
+      # Download a file from the given URL with caching support.
+      #
+      # If the file exists in cache, it will be copied from cache instead of downloading.
+      # If the cached file fails SHA1 verification, it will be invalidated and re-downloaded.
+      # If multiple processes attempt to download the same file, only one will download
+      # while others wait for the download to complete.
+      # HTTP redirects are followed automatically by the HTTP layer.
+      #
+      # @param url [URI::HTTPS] URL to download from
+      # @param output [Pathname] path to save the downloaded file
+      # @param expected_sha1 [String, nil] expected SHA1 digest for verification (optional)
+      # @return [void]
+      # @raise [URLError] if the URL is not HTTPS
+      # @raise [HTTPClientError] for 4xx HTTP errors
+      # @raise [HTTPServerError] for 5xx HTTP errors
+      # @raise [DigestMismatchError] if SHA1 verification fails
+      def download(url, output, expected_sha1: nil)
+        unless url.is_a?(URI::HTTPS)
+          logger.error "Invalid URL: must be HTTPS"
+          raise URLError, "URL must be HTTPS"
+        end
+
+        logger.info("Starting download", output: output.to_s)
+        key = cache.key_for(url.to_s)
+
+        case try_cache_hit(key, output, expected_sha1:)
+        when :hit
+          return
+        when :miss
+          logger.debug("Cache miss, downloading", output: output.to_s)
+          publish("cache.miss", output: output.to_s)
+        when :corrupted
+          logger.debug("Re-downloading after cache invalidation", output: output.to_s)
+          publish("cache.miss", output: output.to_s)
+        else
+          raise RuntimeError, "Unexpected cache state"
+        end
+
+        cache.with_lock(key) do
+          return if try_cache_hit(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)
+          end
+        end
+      end
+
+      # Download file with progress tracking
+      #
+      # @param url [URI::HTTPS] URL to download from
+      # @param output [Pathname] path to save the downloaded file
+      # @return [void]
+      private def download_file_with_progress(url, output)
+        total_size = nil
+        current_size = 0
+
+        client.get(url) do |response|
+          content_length = response["Content-Length"]
+          total_size = content_length ? Integer(content_length, 10) : nil
+
+          publish("download.started", total_size:)
+
+          output.open("wb") do |file|
+            response.read_body do |chunk|
+              file.write(chunk)
+              current_size += chunk.bytesize
+              publish("download.progress", current_size:, total_size:)
+            end
+          end
+        end
+
+        publish("download.completed", total_size: current_size)
+      end
+
+      # Attempt to retrieve file from cache with SHA1 verification.
+      #
+      # 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 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)
+
+        logger.info("Cache hit", output: output.to_s)
+        verify_sha1(output, expected_sha1) if expected_sha1
+        total_size = cache.size(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)
+        :corrupted
+      end
+
+      # Verify SHA1 digest of a file
+      #
+      # @param file [Pathname] file to verify
+      # @param expected_sha1 [String] expected SHA1 digest
+      # @return [void]
+      # @raise [DigestMismatchError] if digest does not match
+      private def verify_sha1(file, expected_sha1)
+        actual_sha1 = Digest(:SHA1).file(file).hexdigest
+        return if actual_sha1 == expected_sha1
+
+        logger.error("SHA1 digest mismatch", expected: expected_sha1, actual: actual_sha1)
+        raise DigestMismatchError, "SHA1 mismatch: expected #{expected_sha1}, got #{actual_sha1}"
+      end
+
+      # Create a temporary file for downloading, ensuring cleanup after use.
+      #
+      # @yield [Pathname] the temporary file path
+      # @return [void]
+      private def with_temporary_file
+        dir = Pathname(Dir.mktmpdir("factorix"))
+        temp_file = dir.join("download")
+        temp_file.binwrite("")
+        yield temp_file
+      ensure
+        temp_file&.unlink if temp_file&.exist?
+        dir&.rmdir if dir&.exist?
+      end
+    end
+  end
+end