v0.7.0

This release overhauls the dictionary loading and caching mechanisms, introducing a more flexible and robust API with improved cross-platform compatibility and safety.

Breaking Changes

• Dictionary::from_path signature has changed.

  • Before: Dictionary::from_path(path) (Unsafe, no validation in release builds)
  • After: Dictionary::from_path(path, mode: LoadMode)
  • Migration: The previous unsafe behavior is now available via the new unsafe fn from_path_unchecked. For safe loading, choose between LoadMode::Validate (always validates) or LoadMode::TrustCache (validates on first run).

  // New recommended usage
  use vibrato_rkyv::{Dictionary, LoadMode};
  let dict = Dictionary::from_path("path/to/dict.dic", LoadMode::TrustCache)?;

• Dictionary::from_zstd signature has changed.

  • Before: Dictionary::from_zstd(path)
  • After: Dictionary::from_zstd(path, strategy: CacheStrategy)
  • Migration: To replicate the old behavior of caching locally, use CacheStrategy::Local. For most applications, CacheStrategy::GlobalCache is now the recommended default.

  // New usage
  use vibrato_rkyv::{Dictionary, CacheStrategy};
  let dict = Dictionary::from_zstd("path/to/dict.zst", CacheStrategy::GlobalCache)?;

• Cache format and location have changed. Caches created with older versions (e.g., decompressed subdirectories, adjacent .sha256 files) will no longer be used and can be safely deleted.

New Features & Enhancements

Unified and Flexible Caching System

The caching logic has been redesigned for both compressed (.zst) and uncompressed (.dic) files to be more maintainability and efficiency.

• CacheStrategy for Compressed Dictionaries: from_zstd now accepts a CacheStrategy to explicitly control cache location, making it usable in read-only environments.
  • CacheStrategy::Local: Caches in a local .cache subdirectory.
  • CacheStrategy::GlobalCache: Caches in a system-wide user cache directory (e.g., ~/.cache/vibrato-rkyv).
  • CacheStrategy::GlobalData: Caches in a system-wide user data directory.
• LoadMode for Uncompressed Dictionaries: from_path now requires a LoadMode for explicit control over the safety/performance trade-off.
  • LoadMode::Validate: Safest option. Performs full validation on every load and never writes cache files.
  • LoadMode::TrustCache: Fastest for reloads. Skips validation if a valid "proof file" exists, creating one in the global cache on the first run.
• Hierarchical & Cross-Platform Cache Validation: Caching now uses a two-tiered validation system. It first performs a near-instant check on file metadata, falling back to a full file hash only when necessary. The metadata hashing is now deterministic across platforms.
• New unsafe fn from_path_unchecked: For advanced users who can guarantee file integrity, this function provides the absolute fastest loading path by skipping all validation.

Legacy Dictionary Support (legacy feature)

When the legacy feature is enabled, vibrato-rkyv can now transparently handle older bincode-based dictionaries.

• Automatic Conversion & Caching: When a legacy dictionary is loaded via from_zstd, it is available for use while a background thread converts and caches it to the rkyv format for faster subsequent loads.
• Safe Background Thread Management: The background caching thread is managed using an RAII pattern,
  which makes a best-effort attempt to complete caching on exit and helps reduce the risk of orphaned temporary files, without blocking the main application.

Other Improvements

• New Public API Dictionary::decompress_zstd: A utility function is now available for manually decompressing and validating dictionary files.
• Safer Dictionary Downloads: The download and extraction process now uses a temporary directory, preventing accidental data loss.
• Enhanced Testing and CI: A comprehensive test suite for the new caching logic has been added, and the CI process has been stabilized for Windows environments.

Pre-compiled Dictionaries

Pre-compiled dictionaries compatible with this version are available at:
https://github.com/stellanomia/vibrato-rkyv/releases/tag/v0.6.2