feat(io): support in-memory local cache

[jerry-024]

Purpose

Add a catalog-scoped in-memory local block cache aligned with Paimon Java. When local-cache.enabled=true, omitting local-cache.dir selects the memory backend; setting a directory keeps the existing persistent disk backend.

Usage and configuration

Create an in-memory cache by enabling local cache without setting local-cache.dir:

let mut options = Options::new();
options.set(CatalogOptions::WAREHOUSE, "s3://bucket/warehouse");
options.set(CatalogOptions::LOCAL_CACHE_ENABLED, "true");
options.set(CatalogOptions::LOCAL_CACHE_MAX_SIZE, "1 GiB");
options.set(CatalogOptions::LOCAL_CACHE_BLOCK_SIZE, "1 MiB");
options.set(
    CatalogOptions::LOCAL_CACHE_WHITELIST,
    "meta,global-index",
);
let catalog = CatalogFactory::create(options).await?;

To use the persistent disk backend instead, add a cache directory before creating the catalog:

options.set(
    CatalogOptions::LOCAL_CACHE_DIR,
    "/var/cache/paimon/worker-1",
);

Option	Default	Behavior
local-cache.enabled	false	Enables local cache when set to true.
local-cache.dir	unset	Unset selects memory; a directory selects persistent disk.
local-cache.max-size	unlimited	Memory accounts payload bytes; disk accounts encoded bytes. Setting a limit is recommended for memory caches.
local-cache.block-size	1 MiB	Size of blocks loaded and cached.
local-cache.whitelist	meta,global-index	Comma-separated file types eligible for caching. Supported values include meta, global-index, bucket-index, data, and file-index.

Size values are case-insensitive and accept Java-style units (b, kb, mb, gb, tb, kib, mib, gib, tib, and their full byte names) plus the existing Rust binary aliases.

The in-memory cache lives for the owning Catalog. Its FileIO clones and REST token-refresh rebuilds reuse the same cache; separate catalogs do not share it. A disk cache persists across catalog lifetimes, and catalogs using the same canonical directory share in-process state.

Brief change log

• Add an access-order in-memory LRU charged by payload bytes, with unlimited capacity when local-cache.max-size is unset and oversized blocks skipped.
• Share block keys, read tokens, single-flight loading, invalidation barriers, and file-size metadata through a cache coordinator while preserving shared-disk-cache concurrency semantics.
• Reuse one memory-size parser for local-cache and core options, including Java unit aliases and existing Rust binary aliases.
• Keep the same cache across Catalog/FileIO clones and REST token-driven FileIO rebuilds.
• Document memory and disk backend selection and capacity accounting.

Tests

• cargo +1.97.0 test -p paimon
• cargo +1.97.0 clippy -p paimon --all-targets -- -D warnings
• cargo fmt --all -- --check
• Added coverage for memory hits, LRU eviction, oversized blocks, single-flight loading, path/prefix invalidation, stale-read prevention, shared disk instances, configuration defaults, and Catalog/REST cache reuse.

API and Format

No public API or storage-format changes. The configuration behavior changes so that enabling local cache without local-cache.dir creates an in-memory cache instead of requiring a disk directory.

Documentation

Updated the getting-started guide with backend selection, defaults, lifetime, and size-accounting behavior.

[JingsongLi]

+1