Module package_cache 

Package Cache Module

High-performance package payload caching for rez-next.

This module provides disk-based caching of package variant payloads to avoid fetching from shared storage at runtime. It follows SOLID principles and incorporates lessons learned from the original rez implementation.

Design Decisions (based on rez issues analysis)

• Cross-platform case handling: Normalizes paths for Windows case-insensitivity
• Disk space pre-check: Fail fast with clear error when disk is full
• Configurable logging: Accepts optional logger instead of hardcoding
• Corrupted data handling: Skips malformed cache entries instead of crashing
• Thread-safe operations: Uses file locking for multi-process safety

Cache Directory Structure

<cache_root>/<package_name>/<version>/<hash_prefix>/<increment>/
                                                   └─ payload files
                                 <increment>.json  └─ variant metadata

The hash is the first 4 chars of SHA1(variant.handle), and increment (a, b, …) handles hash collisions.

Structs

CacheConfig

Configuration for package cache behavior.

CachedVariantInfo

Metadata stored alongside a cached variant payload.

CleanStats

Statistics from a cache cleaning operation.

PackageCache

High-performance package payload cache.

VariantHandle

Serializable representation of a variant handle.

Enums

CacheStatus

Status of a variant in the cache.

PackageCacheError

Errors that can occur during cache operations.