factorix 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eb581275b20274cebfa09669eb5f0111ed00f358d5a68947333b5990eb04d56
-  data.tar.gz: 2a57a400c94476e860c2647af1e8fb3f845b231b1e377e265bfcc1d1de11d7ef
+  metadata.gz: f1d6b99d769a238f64676cfd19aef4d0f8852d2dc38df210eb753a8bc202f67f
+  data.tar.gz: c51b472d2eb47e7d0d39c4789112da30faf5fbf7e225da330d19e989bce86f43
 SHA512:
-  metadata.gz: 9134480ff3cd2675216f6fc9407bb0719467c2488a43449c727294f5871289cb955b6b5a20257314e11d562a60e2eea8edf81bf72c8df739055675142dff8ad5
-  data.tar.gz: 15630f358ac2dbe3ae85b3a0798fdea532b7d9cba43352ffc982c74cf6e5eea1a264329f9543c26100618c7d3e45c2b6cc8a69bf5aca203333a2c77157b68571
+  metadata.gz: 0e9bf68578d26f4b08e77028b1da59ff8d972f807822be5fa19ca1eb951e89412a3314a3db5fde1fcd821f399ee6c9e4e8c28e37d2d0c5e3d000046c5e663d2f
+  data.tar.gz: 81222393a0ab0a6b6e2cbbccac52dec243d4806ef688a1240a01367142094e368175caba564d4842ebd627ebdef98e322f8217b14a3424e8e20c7bbeddc248a4

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [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/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/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_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

data/lib/factorix/cache/file_system.rb

@@ -2,6 +2,7 @@
 
 require "digest"
 require "fileutils"
+require "json"
 require "pathname"
 require "zlib"
 
@@ -12,7 +13,12 @@ module Factorix
     # 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
+    #
+    # Cache entries consist of:
+    # - Data file: the cached content (optionally compressed)
+    # - Metadata file (.metadata): JSON containing the logical key
+    # - Lock file (.lock): used for concurrent access control
+    class FileSystem < Base
       # @!parse
       #   # @return [Dry::Logger::Dispatcher]
       #   attr_reader :logger
@@ -29,52 +35,46 @@ module Factorix
       private_constant :ZLIB_CMF_BYTE
 
       # Initialize a new file system cache storage.
-      # Creates the cache directory if it doesn't exist
+      # Creates the cache directory if it doesn't exist.
+      # Cache directory is auto-calculated as: factorix_cache_dir / cache_type
       #
-      # @param cache_dir [Pathname] path to the cache directory
-      # @param ttl [Integer, nil] time-to-live in seconds (nil for unlimited)
+      # @param cache_type [Symbol] cache type for directory name (e.g., :api, :download)
       # @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
+      # @param ttl [Integer, nil] time-to-live in seconds (nil for unlimited)
+      def initialize(cache_type:, max_file_size: nil, compression_threshold: nil, **)
+        super(**)
+        @cache_dir = Container[:runtime].factorix_cache_dir / cache_type.to_s
         @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)
+        logger.info("Initializing cache", root: @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
+      # @param key [String] logical cache key
       # @return [Boolean] true if the cache entry exists and is valid, false otherwise
       def exist?(key)
-        return false unless cache_path_for(key).exist?
+        internal_key = storage_key_for(key)
+        return false unless cache_path_for(internal_key).exist?
         return true if @ttl.nil?
 
         !expired?(key)
       end
 
-      # Fetch a cached file and copy it to the output path.
+      # Write cached content to a file.
       # 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)
+      # @param key [String] logical cache key
+      # @param output [Pathname] path to write the cached content to
+      # @return [Boolean] true if written successfully, false if not found/expired
+      def write_to(key, output)
+        internal_key = storage_key_for(key)
+        path = cache_path_for(internal_key)
         unless path.exist?
           logger.debug("Cache miss", key:)
           return false
@@ -96,21 +96,21 @@ module Factorix
         true
       end
 
-      # Read a cached file as a string.
+      # Read a cached file as a binary 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)
+      # @param key [String] logical cache key
       # @return [String, nil] cached content or nil if not found/expired
-      def read(key, encoding: Encoding::ASCII_8BIT)
-        path = cache_path_for(key)
+      def read(key)
+        internal_key = storage_key_for(key)
+        path = cache_path_for(internal_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)
+        data
       end
 
       # Store a file in the cache.
@@ -118,7 +118,7 @@ module Factorix
       # 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 key [String] logical cache key
       # @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)
@@ -135,22 +135,30 @@ module Factorix
           return false
         end
 
-        path = cache_path_for(key)
+        internal_key = storage_key_for(key)
+        path = cache_path_for(internal_key)
+        metadata_path = metadata_path_for(internal_key)
+
         path.dirname.mkpath
         path.binwrite(data)
+        metadata_path.write(JSON.generate({logical_key: key}))
         logger.debug("Stored in cache", key:, size_bytes: data.bytesize)
         true
       end
 
       # Delete a specific cache entry.
       #
-      # @param key [String] cache key to delete
+      # @param key [String] logical cache key
       # @return [Boolean] true if the entry was deleted, false if it didn't exist
       def delete(key)
-        path = cache_path_for(key)
+        internal_key = storage_key_for(key)
+        path = cache_path_for(internal_key)
+        metadata_path = metadata_path_for(internal_key)
+
         return false unless path.exist?
 
         path.delete
+        metadata_path.delete if metadata_path.exist?
         logger.debug("Deleted from cache", key:)
         true
       end
@@ -160,13 +168,14 @@ module Factorix
       #
       # @return [void]
       def clear
-        logger.info("Clearing cache directory", dir: @cache_dir.to_s)
+        logger.info("Clearing cache directory", root: @cache_dir.to_s)
         count = 0
         @cache_dir.glob("**/*").each do |path|
-          if path.file?
-            path.delete
-            count += 1
-          end
+          next unless path.file?
+          next if path.extname == ".lock"
+
+          path.delete
+          count += 1
         end
         logger.info("Cache cleared", files_removed: count)
       end
@@ -174,10 +183,11 @@ module Factorix
       # Get the age of a cache entry in seconds.
       # Returns nil if the entry doesn't exist.
       #
-      # @param key [String] cache key
+      # @param key [String] logical cache key
       # @return [Float, nil] age in seconds, or nil if entry doesn't exist
       def age(key)
-        path = cache_path_for(key)
+        internal_key = storage_key_for(key)
+        path = cache_path_for(internal_key)
         return nil unless path.exist?
 
         Time.now - path.mtime
@@ -186,7 +196,7 @@ module Factorix
       # 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
+      # @param key [String] logical cache key
       # @return [Boolean] true if expired, false otherwise
       def expired?(key)
         return false if @ttl.nil?
@@ -200,10 +210,11 @@ module Factorix
       # 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
+      # @param key [String] logical 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)
+        internal_key = storage_key_for(key)
+        path = cache_path_for(internal_key)
         return nil unless path.exist?
         return nil if expired?(key)
 
@@ -211,13 +222,14 @@ module Factorix
       end
 
       # Executes the given block with a file lock.
-      # Uses flock for process-safe file locking and automatically removes stale locks
+      # Uses flock for process-safe file locking and automatically removes stale locks.
       #
-      # @param key [String] cache key to lock
+      # @param key [String] logical cache key
       # @yield Executes the block with exclusive file lock
       # @return [void]
       def with_lock(key)
-        lock_path = lock_path_for(key)
+        internal_key = storage_key_for(key)
+        lock_path = lock_path_for(internal_key)
         cleanup_stale_lock(lock_path)
 
         lock_path.dirname.mkpath
@@ -240,23 +252,83 @@ module Factorix
         end
       end
 
-      # Get the cache file path for the given key.
+      # Enumerate cache entries.
+      #
+      # Yields [key, entry] pairs similar to Hash#each.
+      # Skips entries without metadata files (legacy entries).
+      #
+      # @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
+      def each
+        return enum_for(__method__) unless block_given?
+
+        @cache_dir.glob("**/*").each do |path|
+          next unless path.file?
+          next if path.extname == ".metadata" || path.extname == ".lock"
+
+          metadata_path = Pathname("#{path}.metadata")
+          next unless metadata_path.exist?
+
+          logical_key = JSON.parse(metadata_path.read)["logical_key"]
+          age = Time.now - path.mtime
+          entry = Entry.new(
+            size: path.size,
+            age:,
+            expired: @ttl ? age > @ttl : false
+          )
+
+          yield logical_key, entry
+        end
+      end
+
+      # Return backend-specific information.
+      #
+      # @return [Hash] backend configuration and status
+      def backend_info
+        {
+          type: "file_system",
+          directory: @cache_dir.to_s,
+          max_file_size: @max_file_size,
+          compression_threshold: @compression_threshold,
+          stale_locks: count_stale_locks
+        }
+      end
+
+      # Generate a storage key for the given logical key.
+      # Uses SHA1 to create a unique, deterministic key.
+      # Use Digest(:SHA1) instead of Digest::SHA1 for thread-safety (Ruby 2.2+)
+      #
+      # @param logical_key [String] logical key to generate storage key for
+      # @return [String] storage key (SHA1 hash)
+      private def storage_key_for(logical_key) = Digest(:SHA1).hexdigest(logical_key)
+
+      # Get the cache file path for the given internal key.
       # Uses a two-level directory structure to avoid too many files in one directory
       #
-      # @param key [String] cache key
+      # @param internal_key [String] internal storage key
       # @return [Pathname] path to the cache file
-      private def cache_path_for(key)
-        prefix = key[0, 2]
-        @cache_dir.join(prefix, key[2..])
+      private def cache_path_for(internal_key)
+        prefix = internal_key[0, 2]
+        @cache_dir.join(prefix, internal_key[2..])
+      end
+
+      # Get the metadata file path for the given internal key.
+      #
+      # @param internal_key [String] internal storage key
+      # @return [Pathname] path to the metadata file
+      private def metadata_path_for(internal_key)
+        Pathname("#{cache_path_for(internal_key)}.metadata")
       end
 
-      # Get the lock file path for the given key.
+      # Get the lock file path for the given internal key.
       # Lock files are stored alongside cache files with a .lock extension
       #
-      # @param key [String] cache key
+      # @param internal_key [String] internal storage key
       # @return [Pathname] path to the lock file
-      private def lock_path_for(key)
-        cache_path_for(key).sub_ext(".lock")
+      private def lock_path_for(internal_key)
+        cache_path_for(internal_key).sub_ext(".lock")
       end
 
       # Check if data should be compressed based on compression_threshold setting.
@@ -302,6 +374,14 @@ module Factorix
           nil
         end
       end
+
+      # Count stale lock files in the cache directory.
+      #
+      # @return [Integer] number of stale lock files
+      private def count_stale_locks
+        cutoff = Time.now - LOCK_FILE_LIFETIME
+        @cache_dir.glob("**/*.lock").count {|path| path.mtime < cutoff }
+      end
     end
   end
 end