Skip to content

v0.6.11

v0.6.11: feat!: Introduce configurable load modes and cross-platform hashing
@o24s o24s tagged this 02 Nov 23:50 
This commit introduces a major breaking change. It adds configurable load modes (`LoadMode`) to `from_path` and implements a robust, deterministic metadata hashing strategy for cross-platform compatibility.

BREAKING CHANGE: The signature of `Dictionary::from_path` has been changed. It now requires a `LoadMode` argument. The previous behavior of loading without validation is now available via the new `unsafe` function `Dictionary::from_path_unchecked`.

These changes improve performance, safety, and portability.

Changes:
  - Added `LoadMode` Enum for `from_path`:
    The `from_path` function now accepts a `LoadMode` argument, allowing users to choose between two strategies:
    - `LoadMode::Validate`: Performs full validation on every load. This is the safest option and does not write any cache files, making it suitable for read-only environments.
    - `LoadMode::TrustCache`: Skips validation if a `.sha256` hash cache file exists and matches the dictionary's metadata. If the cache is missing or invalid, it falls back to full validation and creates/updates the cache file for subsequent loads.

  - Introduced `from_path_unchecked`:
    A new `unsafe` function `from_path_unchecked` has been added. It loads a dictionary via memory-mapping without any validation checks, providing the minimal-load-overhead path. This function now encapsulates the behavior of the previous `from_path`, which was always unchecked in release builds. It is used internally by `TrustCache` mode and is available for advanced users who can guarantee file integrity.

  - Implemented Cross-Platform Metadata Hashing:
    The file hashing function has been enhanced to be deterministic across different platforms.
    - Unix/Windows: Continues to use platform-specific, high-precision metadata (inode, device ID, etc.).
    - Other Platforms (`cfg(not(any(unix, windows)))`): A new portable implementation has been added based on a well-defined specification. It serializes file size, file type, readonly permission, and nanosecond-precision timestamps (`modified`, `created`) into a canonical byte stream.

  - Updated `from_zstd` Caching Logic:
    The zstd decompression and caching logic has been updated to leverage the new `LoadMode` and `from_path_unchecked` functions, resulting in cleaner and more efficient cache handling.

These changes provide users with greater control over the trade-off between loading speed and safety.
Assets 2
Loading