feat(io): implement CacheIO read-cache layer for disk IO

[LHT129]

Summary

Add CacheIO template class that provides a page-based read cache in front of any disk-backed IO implementation. All reads go through the cache; writes passthrough directly to the inner IO with no cache involvement.

Closes #2420

Design

• Architecture: CacheIO : BasicIO<CacheIO> - follows existing CRTP IO pattern
• Page-based caching: configurable page size (default 128KB)
• Total cache size: configurable with default 256MB
• Eviction: pluggable EvictionStrategy interface, LRU as first implementation
• Read path: all reads go through cache; miss loads page from InnerIO
• Write path: direct passthrough to InnerIO, no cache invalidation needed
• DirectRead: single-page hit returns internal cache pointer (need_release=false); cross-page copies to new buffer (need_release=true)
• Thread safety: mutex-protected cache with LRU eviction

Components

• src/io/cache_io/eviction_strategy.h - EvictionStrategy interface + LRUEviction implementation
• src/io/cache_io/cache_io_parameter.h/.cpp - CacheIOParameter (page_size, total_cache_size, eviction_strategy)
• src/io/cache_io/cache_io.h - CacheIO template class
• src/io/cache_io/cache_io_test.cpp - Unit tests (basic R/W, eviction, direct read, multi-read, parameters)

Testing

• 6 test cases, 6322 assertions, all passing
• No regression in existing IO tests (BufferIO, NonContinuousIO, etc.)

[vsag-bot]

/label S-waiting-on-review
/waiting-on reviewer
/request-review @jiaweizone
/request-review @wxyucs
/request-review @inabao

[mergify]

Merge Protections

🟢 All 3 merge protections satisfied — ready to merge.

Show 3 satisfied protections

🟢 Require kind label

• label~=^kind/

🟢 Require version label

• label~=^version/

🟢 Require linked issue for feature/bug PRs

• body~=(?im)(?:^|[\s\-\*])(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s*:?\s+(?:#\d+|[\w.\-]+/[\w.\-]+#\d+|https?://github\.com/[\w.\-]+/[\w.\-]+/issues/\d+)

[gemini-code-assist]

Code Review

This pull request introduces CacheIO, a page-based read-cache IO layer wrapping an underlying disk-backed IO implementation, along with its configuration parameters, an LRU eviction strategy, and unit tests. The review feedback highlights several critical issues that must be addressed: potential Use-After-Free (UAF) vulnerabilities in ReadImpl and DirectReadImpl due to race conditions and lack of page pinning, uninitialized and un-updated this->size_ values that will cause read operations to fail, a potential division-by-zero crash if page_size is configured as zero, and a redundant if-else block during eviction strategy initialization.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Copilot]

Pull request overview

This PR introduces a new CacheIO<InnerIO> CRTP IO wrapper that adds a page-based in-memory read cache in front of an underlying IO implementation, plus JSON-parseable parameters and unit tests.

Changes:

• Added CacheIO<InnerIO> template with page caching, LRU eviction, and DirectRead/MultiRead support.
• Added CacheIOParameter (JSON serialization/parsing) and EvictionStrategy/LRUEviction.
• Wired cache_io into IO parameter parsing and header aggregation; added unit tests.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/io/io_headers.h	Exposes cache_io.h through the IO header umbrella.
src/io/common/io_parameter.cpp	Adds JSON parsing support for type=cache_io parameters.
src/io/CMakeLists.txt	Builds cache_io_parameter.cpp as part of the IO object library.
src/io/cache_io/eviction_strategy.h	Introduces eviction strategy interface and LRU implementation.
src/io/cache_io/cache_io.h	Implements the CacheIO read-cache IO wrapper.
src/io/cache_io/cache_io_test.cpp	Adds unit tests for caching, eviction, direct read, multiread, and parameters.
src/io/cache_io/cache_io_parameter.h	Declares CacheIOParameter (page size, total cache size, eviction strategy).
src/io/cache_io/cache_io_parameter.cpp	Implements JSON (de)serialization for CacheIOParameter.
src/inner_string_params.h	Registers the cache_io IO type string.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 8 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 10 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 8 comments.