factorix 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eb581275b20274cebfa09669eb5f0111ed00f358d5a68947333b5990eb04d56
-  data.tar.gz: 2a57a400c94476e860c2647af1e8fb3f845b231b1e377e265bfcc1d1de11d7ef
+  metadata.gz: 3cc75b1211b8487fb9f93c19751c2086415385d32356282dfd3d71ef4158fdd1
+  data.tar.gz: 8d55640b9704c518ec15660cf17604b6f89b96356bee3044e5e663d28afebca0
 SHA512:
-  metadata.gz: 9134480ff3cd2675216f6fc9407bb0719467c2488a43449c727294f5871289cb955b6b5a20257314e11d562a60e2eea8edf81bf72c8df739055675142dff8ad5
-  data.tar.gz: 15630f358ac2dbe3ae85b3a0798fdea532b7d9cba43352ffc982c74cf6e5eea1a264329f9543c26100618c7d3e45c2b6cc8a69bf5aca203333a2c77157b68571
+  metadata.gz: 638164922741c6f7225125b1c1f676c21adc5253e7ab1e40a99c0c6baef3f1e3d554097a254cf3cc4cb0ffc4e055c9153c4a37132222216ea00097cbf24f044c
+  data.tar.gz: dfc7c5bce1df717c321f2189d78486a0443d640e7c32571dd0038b07f34c7be5da68b72e5aa12c9ed1de59ca55531b37937a4cc9194d15aea88ff6a834d6cd95

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 ## [Unreleased]
 
+## [0.8.0] - 2026-02-03
+
+### Added
+
+- Add `download` command to download Factorio game files from the official Download API (#51)
+  - Supports alpha, expansion, demo, and headless builds
+  - Auto-detects platform (Windows, Linux, macOS, WSL)
+  - Resolves latest version from stable/experimental channels
+- Add `head` method to HTTP client and decorators (`Client`, `RetryDecorator`, `CacheDecorator`)
+
+## [0.7.0] - 2026-01-24
+
+### Added
+
+- Add pluggable cache backend architecture with Redis and S3 support (#18, #19)
+  - Configure backend per cache type: `config.cache.<type>.backend = :file_system | :redis | :s3`
+  - **Redis backend** (`Cache::Redis`): requires `redis` gem (~> 5)
+    - Distributed locking via Lua script for atomic lock release
+    - Auto-namespaced keys: `factorix-cache:{cache_type}:{key}`
+  - **S3 backend** (`Cache::S3`): requires `aws-sdk-s3` gem
+    - Distributed locking via conditional PUT (`if_none_match: "*"`)
+    - TTL managed via S3 custom metadata, age from native `Last-Modified`
+  - `cache stat` command displays backend-specific information (directory, URL, bucket, etc.)
+
+### Changed
+
+- Refactor `Cache::FileSystem` to use `cache_type:` parameter instead of `root:` (#25)
+  - Aligns interface with other backends for consistent initialization
+  - Cache directory is now auto-computed from `Container[:runtime].factorix_cache_dir / cache_type`
+
+### Removed
+
+- Remove deprecated `Factorix::Application` compatibility class
+  - Use `Factorix::Container` for DI (`[]`, `resolve`, `register`)
+  - Use `Factorix.config` and `Factorix.configure` for configuration
+
 ## [0.6.0] - 2026-01-18
 
 ### Changed

data/README.md

@@ -20,6 +20,7 @@ Factorix simplifies Factorio MOD management by providing:
 - **Settings Management**: Export/import MOD settings in JSON format
 - **MOD Portal Integration**: Upload new MODs or update existing ones, edit metadata
 - **Game Control**: Launch Factorio from the command line
+- **Game Download**: Download Factorio game files (alpha, expansion, demo, headless)
 - **Cross-platform Support**: Works on Windows, Linux, macOS, and WSL
 
 ## Requirements
@@ -38,6 +39,8 @@ export FACTORIO_API_KEY=your_api_key_here
 
 API key is not required for downloading, installing, or managing local MODs.
 
+For downloading the game itself (`factorix download`), service credentials are required. These are automatically loaded from `player-data.json` if you have logged into Factorio, or you can set `FACTORIO_USERNAME` and `FACTORIO_TOKEN` environment variables.
+
 ## Configuration
 
 ### Path Configuration

data/completion/_factorix.bash

@@ -17,7 +17,7 @@ _factorix() {
   local confirmable_opts="-y --yes"
 
   # Top-level commands
-  local commands="version man launch path mod cache completion"
+  local commands="version man launch path download mod cache completion"
 
   # mod subcommands
   local mod_commands="check list show enable disable install uninstall update download upload edit search sync image settings"
@@ -52,6 +52,20 @@ _factorix() {
       fi
       return
       ;;
+    download)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=($(compgen -W "$global_opts -b --build -p --platform -c --channel -d --directory -o --output" -- "$cur"))
+      elif [[ "$prev" == "--build" ]] || [[ "$prev" == "-b" ]]; then
+        COMPREPLY=($(compgen -W "alpha expansion demo headless" -- "$cur"))
+      elif [[ "$prev" == "--platform" ]] || [[ "$prev" == "-p" ]]; then
+        COMPREPLY=($(compgen -W "win64 win64-manual osx linux64" -- "$cur"))
+      elif [[ "$prev" == "--channel" ]] || [[ "$prev" == "-c" ]]; then
+        COMPREPLY=($(compgen -W "stable experimental" -- "$cur"))
+      elif [[ "$prev" == "--directory" ]] || [[ "$prev" == "-d" ]]; then
+        COMPREPLY=($(compgen -d -- "$cur"))
+      fi
+      return
+      ;;
     cache)
       if [[ $cword -eq 2 ]]; then
         COMPREPLY=($(compgen -W "$cache_commands" -- "$cur"))

data/completion/_factorix.fish

@@ -73,13 +73,14 @@ complete -c factorix -l log-level -d 'Set log level' -xa 'debug info warn error
 complete -c factorix -s q -l quiet -d 'Suppress non-essential output'
 
 # Top-level commands
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a version -d 'Display Factorix version'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a man -d 'Display the Factorix manual page'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a launch -d 'Launch Factorio game'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a path -d 'Display Factorio and Factorix paths'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a mod -d 'MOD management commands'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a cache -d 'Cache management commands'
-complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a completion -d 'Generate shell completion script'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a version -d 'Display Factorix version'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a man -d 'Display the Factorix manual page'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a launch -d 'Launch Factorio game'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a path -d 'Display Factorio and Factorix paths'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a download -d 'Download Factorio game files'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a mod -d 'MOD management commands'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a cache -d 'Cache management commands'
+complete -c factorix -n "not __factorix_using_command version; and not __factorix_using_command man; and not __factorix_using_command launch; and not __factorix_using_command path; and not __factorix_using_command download; and not __factorix_using_command mod; and not __factorix_using_command cache; and not __factorix_using_command completion" -a completion -d 'Generate shell completion script'
 
 # launch options
 complete -c factorix -n "__factorix_using_command launch" -s w -l wait -d 'Wait for the game to finish'
@@ -90,6 +91,13 @@ complete -c factorix -n "__factorix_using_command path" -l json -d 'Output in JS
 # completion shell argument
 complete -c factorix -n "__factorix_using_command completion" -a 'zsh bash fish' -d 'Shell type'
 
+# download options
+complete -c factorix -n "__factorix_using_command download" -s b -l build -d 'Build type' -xa 'alpha expansion demo headless'
+complete -c factorix -n "__factorix_using_command download" -s p -l platform -d 'Platform' -xa 'win64 win64-manual osx linux64'
+complete -c factorix -n "__factorix_using_command download" -s c -l channel -d 'Release channel' -xa 'stable experimental'
+complete -c factorix -n "__factorix_using_command download" -s d -l directory -d 'Download directory' -ra '(__fish_complete_directories)'
+complete -c factorix -n "__factorix_using_command download" -s o -l output -d 'Output filename' -r
+
 # cache subcommands
 complete -c factorix -n "__factorix_using_command cache" -a stat -d 'Display cache statistics'
 complete -c factorix -n "__factorix_using_command cache" -a evict -d 'Evict cache entries'

data/completion/_factorix.zsh

@@ -39,6 +39,7 @@ _factorix() {
         'man:Display the Factorix manual page'
         'launch:Launch Factorio game'
         'path:Display Factorio and Factorix paths'
+        'download:Download Factorio game files'
         'mod:MOD management commands'
         'cache:Cache management commands'
         'completion:Generate shell completion script'
@@ -61,6 +62,9 @@ _factorix() {
             $global_opts \
             '--json[Output in JSON format]'
           ;;
+        download)
+          _factorix_download
+          ;;
         completion)
           _factorix_completion
           ;;
@@ -88,6 +92,24 @@ _factorix_completion() {
     '1:shell:(zsh bash fish)'
 }
 
+_factorix_download() {
+  local -a global_opts
+  global_opts=(
+    '(-c --config-path)'{-c,--config-path}'[Path to configuration file]:config file:_files'
+    '--log-level[Set log level]:level:(debug info warn error fatal)'
+    '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+  )
+
+  _arguments \
+    $global_opts \
+    '(-b --build)'{-b,--build}'[Build type]:build:(alpha expansion demo headless)' \
+    '(-p --platform)'{-p,--platform}'[Platform]:platform:(win64 win64-manual osx linux64)' \
+    '(-c --channel)'{-c,--channel}'[Release channel]:channel:(stable experimental)' \
+    '(-d --directory)'{-d,--directory}'[Download directory]:directory:_files -/' \
+    '(-o --output)'{-o,--output}'[Output filename]:filename:' \
+    '1:version:'
+}
+
 _factorix_mod() {
   local context state state_descr line
   typeset -A opt_args

data/exe/factorix

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

data/lib/factorix/api/game_download_api.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Factorix
+  module API
+    # API client for downloading Factorio game files
+    #
+    # Corresponds to: https://wiki.factorio.com/Download_API
+    class GameDownloadAPI
+      # @!parse
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      #   # @return [HTTP::Client]
+      #   attr_reader :client
+      include Import[:logger, client: :api_http_client]
+
+      # Base URL for game downloads
+      DOWNLOAD_BASE_URL = "https://www.factorio.com"
+      private_constant :DOWNLOAD_BASE_URL
+
+      # Base URL for API endpoints
+      API_BASE_URL = "https://factorio.com"
+      private_constant :API_BASE_URL
+
+      # Valid build types
+      BUILDS = %w[alpha expansion demo headless].freeze
+      public_constant :BUILDS
+
+      # Valid platforms
+      PLATFORMS = %w[win64 win64-manual osx linux64].freeze
+      public_constant :PLATFORMS
+
+      # Valid release channels
+      CHANNELS = %w[stable experimental].freeze
+      public_constant :CHANNELS
+
+      # Initialize with thread-safe credential loading
+      #
+      # @param args [Hash] dependency injection arguments
+      def initialize(...)
+        super
+        @service_credential_mutex = Mutex.new
+      end
+
+      # Fetch latest release information
+      #
+      # @return [Hash{Symbol => Hash}] Hash containing stable and experimental release info
+      # @example Response format
+      #   {
+      #     stable: { alpha: "2.0.28", expansion: "2.0.28", headless: "2.0.28" },
+      #     experimental: { alpha: "2.0.29", expansion: "2.0.29", headless: "2.0.29" }
+      #   }
+      def latest_releases
+        logger.debug "Fetching latest releases"
+        uri = URI.join(API_BASE_URL, "/api/latest-releases")
+        response = client.get(uri)
+        JSON.parse((+response.body).force_encoding(Encoding::UTF_8), symbolize_names: true)
+      end
+
+      # Get the latest version for a specific channel and build
+      #
+      # @param channel [String] Release channel (stable, experimental)
+      # @param build [String] Build type (alpha, expansion, demo, headless)
+      # @return [String, nil] Version string or nil if not available
+      def latest_version(channel:, build:)
+        releases = latest_releases
+        releases.dig(channel.to_sym, build.to_sym)
+      end
+
+      # Resolve the download filename by making a HEAD request
+      #
+      # @param version [String] Game version (e.g., "2.0.28")
+      # @param build [String] Build type (alpha, expansion, demo, headless)
+      # @param platform [String] Platform (win64, win64-manual, osx, linux64)
+      # @return [String] Filename extracted from final redirect URL
+      # @raise [ArgumentError] if build or platform is invalid
+      def resolve_filename(version:, build:, platform:)
+        validate_build!(build)
+        validate_platform!(platform)
+
+        uri = build_download_uri(version, build, platform)
+        response = client.head(uri)
+        File.basename(response.uri.path)
+      end
+
+      # Download the game to the specified output path
+      #
+      # @param version [String] Game version (e.g., "2.0.28")
+      # @param build [String] Build type (alpha, expansion, demo, headless)
+      # @param platform [String] Platform (win64, win64-manual, osx, linux64)
+      # @param output [Pathname] Output file path
+      # @param handler [Object, nil] Event handler for download progress (optional)
+      # @return [void]
+      # @raise [ArgumentError] if build or platform is invalid
+      def download(version:, build:, platform:, output:, handler: nil)
+        validate_build!(build)
+        validate_platform!(platform)
+
+        uri = build_download_uri(version, build, platform)
+        downloader = Container[:downloader]
+        downloader.subscribe(handler) if handler
+        begin
+          downloader.download(uri, output)
+        ensure
+          downloader.unsubscribe(handler) if handler
+        end
+      end
+
+      # Build the download URI with authentication
+      #
+      # @param version [String] Game version
+      # @param build [String] Build type
+      # @param platform [String] Platform
+      # @return [URI::HTTPS] Complete download URI with credentials
+      private def build_download_uri(version, build, platform)
+        path = "/get-download/#{version}/#{build}/#{platform}"
+        uri = URI.join(DOWNLOAD_BASE_URL, path)
+        params = {username: service_credential.username, token: service_credential.token}
+        uri.query = URI.encode_www_form(params)
+        uri
+      end
+
+      private def service_credential
+        return @service_credential if defined?(@service_credential)
+
+        @service_credential_mutex.synchronize do
+          @service_credential ||= Container[:service_credential]
+        end
+      end
+
+      # Validate build type
+      #
+      # @param build [String] Build type to validate
+      # @raise [ArgumentError] if build type is invalid
+      private def validate_build!(build)
+        return if BUILDS.include?(build)
+
+        raise ArgumentError, "Invalid build type: #{build}. Valid types: #{BUILDS.join(", ")}"
+      end
+
+      # Validate platform
+      #
+      # @param platform [String] Platform to validate
+      # @raise [ArgumentError] if platform is invalid
+      private def validate_platform!(platform)
+        return if PLATFORMS.include?(platform)
+
+        raise ArgumentError, "Invalid platform: #{platform}. Valid platforms: #{PLATFORMS.join(", ")}"
+      end
+    end
+  end
+end

data/lib/factorix/api/mod_download_api.rb

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

data/lib/factorix/api/mod_info.rb

@@ -152,7 +152,7 @@ module Factorix
 
         # Filter detail_fields to only include keys that Detail.new accepts
         # Exclude deprecated fields like github_path
-        detail = Detail.new(**detail_fields.slice(*DETAIL_ALLOWED_KEYS)) if all_required_detail_fields?(detail_fields)
+        detail = Detail[**detail_fields.slice(*DETAIL_ALLOWED_KEYS)] if all_required_detail_fields?(detail_fields)
 
         super(name:, title:, owner:, summary:, downloads_count:, category:, score:, thumbnail:, latest_release:, releases:, detail:)
       end

data/lib/factorix/api/mod_portal_api.rb

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

data/lib/factorix/cache/base.rb

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

data/lib/factorix/cache/entry.rb

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