Cache volumes: RAM cache settings and remap option

[zwoop]

This adds new configuration options for volume.config, as well as
adding an @volume= setting to remap.config (avoiding the hosting.config
stepping stone).

[Copilot]

Pull request overview

This PR adds per-volume RAM cache configuration and a new @volume= remap directive, providing fine-grained control over cache volume selection and RAM cache allocation beyond the existing hostname-based volume selection mechanism.

• Introduces ram_cache_size and ram_cache_cutoff parameters in volume.config for per-volume RAM cache control
• Adds @volume= directive in remap.config to override default volume selection
• Implements private RAM cache allocation with automatic subtraction from the global pool

Reviewed changes

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

Show a summary per file

File	Description
tests/gold_tests/cache/cache_volume_features.test.py	Test suite entry point for cache volume features
tests/gold_tests/cache/cache_volume_features.replay.yaml	Comprehensive test scenarios covering volume selection and RAM cache configurations
src/proxy/http/remap/RemapProcessor.cc	Integrates cache_volume override from remap rules into transaction state
src/proxy/http/remap/RemapConfig.cc	Parses and validates @Volume= option from remap.config
src/proxy/http/HttpCacheSM.cc	Passes volume override to cache operations (open_read/open_write)
src/iocore/cache/Stripe.h	Adds ram_cache_size and ram_cache_cutoff fields to CacheVol structure
src/iocore/cache/P_CacheHosting.h	Adds ram_cache_size and ram_cache_cutoff to ConfigVol structure
src/iocore/cache/P_CacheInternal.h	Updates Cache::open_read/open_write/key_to_stripe signatures with volume_override parameter
src/iocore/cache/CacheVC.cc	Implements per-volume RAM cache cutoff logic using volume-specific or global settings
src/iocore/cache/CacheProcessor.cc	Implements private RAM allocation calculation and shared pool distribution
src/iocore/cache/CacheHosting.cc	Parses ram_cache_size and ram_cache_cutoff from volume.config
src/iocore/cache/Cache.cc	Implements volume override selection logic in key_to_stripe function
include/proxy/http/remap/UrlMapping.h	Adds cache_volume field to url_mapping class
include/proxy/http/remap/RemapConfig.h	Defines REMAP_OPTFLG_VOLUME flag for volume option
include/proxy/http/HttpTransact.h	Adds cache_volume_override field to transaction state
include/iocore/cache/Cache.h	Updates CacheProcessor API signatures with volume_override parameter
doc/admin-guide/files/volume.config.en.rst	Documents ram_cache_size and ram_cache_cutoff configuration options
doc/admin-guide/files/remap.config.en.rst	Documents @Volume= directive usage and behavior
doc/admin-guide/files/records.yaml.en.rst	Documents interaction between global and per-volume RAM cache settings
configs/volume.config.default	Adds examples and documentation for new RAM cache parameters

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

[zwoop]

[approve ci autest 1]

[zwoop]

I've addressed CoPilot's reviews again.

[bryancall]

Overall: Approve with comments

Solid feature PR. The 4-tier priority system in key_to_stripe() is clean, the RAM cache subtraction math is correct, and the deferred initialization pattern for @volume= is well-reasoned for the startup ordering constraint. A few items worth addressing:

Medium Priority

1. Lowercase size suffixes silently produce wrong values. ink_atoi64 only recognizes uppercase K, M, G, T, but the suffix-skip loops in BuildListFromString accept both cases (strchr("kmgtKMGT", *tmp)). So ram_cache_size=2g parses as 2 bytes, not 2GB, with no warning. Same issue for avg_obj_size, fragment_size, and ram_cache_cutoff. Either restrict the skip loop to uppercase only (to match ink_atoi64), or document that suffixes are case-sensitive.

2. @volume= character validation is too permissive. The validation loop allows degenerate inputs like @volume=,,, @volume=0, @volume=,1,, and @volume=999. For the eager path (cache ready), createCacheHostRecord() catches bad volume numbers. But for the deferred path (initial startup), the string is stored as-is and errors only surface later as a non-fatal Error() log — ATS keeps running with no volume override for that rule. Consider validating individual volume numbers (1–255, no empty segments) during remap parsing.

Low Priority / Informational

3. @volume=99 in the features test — if volume 99 isn't defined in volume.config, createCacheHostRecord() will fail. During initial startup this is deferred and the error is swallowed (logged but non-fatal). The test may only pass because of deferred init. Worth verifying this is the intended behavior, or adding an explicit "invalid volume gracefully degrades" test.

4. Brief startup window where @volume= rules don't take effect — if wait_for_cache is disabled, requests arriving between remap load and CB_After_Cache_Init will see volume_host_rec == nullptr and fall through to the normal priority chain. This is correct degradation, but worth a note in the docs.

5. No test for hosting.config + @volume= priority interaction — the 4-tier priority is documented but only tiers 1, 3, and 4 are tested. A test showing @volume= overriding a hostname match from hosting.config would strengthen confidence.

[bryancall]

Overall: Approve with comments

Solid feature PR. The 4-tier priority system in key_to_stripe() is clean, the RAM cache subtraction math is correct, and the deferred initialization pattern for @volume= is well-reasoned for the startup ordering constraint. A few items worth addressing:

Medium Priority

1. Lowercase size suffixes silently produce wrong values. ink_atoi64 only recognizes uppercase K, M, G, T, but the suffix-skip loops in BuildListFromString accept both cases (strchr("kmgtKMGT", *tmp)). So ram_cache_size=2g parses as 2 bytes, not 2GB, with no warning. Same issue for avg_obj_size, fragment_size, and ram_cache_cutoff. Either restrict the skip loop to uppercase only (to match ink_atoi64), or document that suffixes are case-sensitive.

2. @volume= character validation is too permissive. The validation loop allows degenerate inputs like @volume=,,, @volume=0, @volume=,1,, and @volume=999. For the eager path (cache ready), createCacheHostRecord() catches bad volume numbers. But for the deferred path (initial startup), the string is stored as-is and errors only surface later as a non-fatal Error() log — ATS keeps running with no volume override for that rule. Consider validating individual volume numbers (1–255, no empty segments) during remap parsing.

Low Priority / Informational

3. @volume=99 in the features test — if volume 99 isn't defined in volume.config, createCacheHostRecord() will fail. During initial startup this is deferred and the error is swallowed (logged but non-fatal). The test may only pass because of deferred init. Worth verifying this is the intended behavior, or adding an explicit "invalid volume gracefully degrades" test.

4. Brief startup window where @volume= rules don't take effect — if wait_for_cache is disabled, requests arriving between remap load and CB_After_Cache_Init will see volume_host_rec == nullptr and fall through to the normal priority chain. This is correct degradation, but worth a note in the docs.

5. No test for hosting.config + @volume= priority interaction — the 4-tier priority is documented but only tiers 1, 3, and 4 are tested. A test showing @volume= overriding a hostname match from hosting.config would strengthen confidence.