feat(Type Cache Deprecation): Add FetchOnlyFromCache flag and enable/disable caching with respect to flag value

[Tulsishah]

Description

• Request Struct Updates: The StatObjectRequest, ListObjectsRequest, and a newly introduced GetFolderRequest now include IsTypeCacheDeprecated and FetchOnlyFromCache flags.
• Cache Miss Handling: In the fastStatBucket implementation, if FetchOnlyFromCache is enabled and a cache miss occurs, the system returns a new CacheMissError instead of falling back to GCS.
• Interface Refactoring: The GetFolder method across various bucket implementations and interfaces (including Bucket, bucketHandle, and debugBucket) was refactored to accept a GetFolderRequest struct rather than a simple string for the folder name

Link to the issue in case of a bug fix.

b/473671143

Testing details

1. Manual - NA
2. Unit tests - Added
3. Integration tests - Automated

Any backward incompatible change? If so, please explain.

[codecov]

Codecov Report

❌ Patch coverage is 79.54545% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.11%. Comparing base (8985dad) to head (db0df34).
⚠️ Report is 9 commits behind head on master.

Files with missing lines	Patch %	Lines
internal/storage/debug_bucket.go	0.00%	3 Missing ⚠️
internal/monitor/bucket.go	0.00%	2 Missing ⚠️
internal/ratelimit/throttled_bucket.go	0.00%	2 Missing ⚠️
internal/storage/caching/fast_stat_bucket.go	86.66%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4243      +/-   ##
==========================================
+ Coverage   83.09%   83.11%   +0.01%     
==========================================
  Files         154      156       +2     
  Lines       18980    19173     +193     
==========================================
+ Hits        15772    15935     +163     
- Misses       2631     2648      +17     
- Partials      577      590      +13     

Flag	Coverage Δ
unittests	83.11% <79.54%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Tulsishah]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors the GetFolder function across various bucket abstraction layers to accept a *gcs.GetFolderRequest struct instead of a direct folder name string, with corresponding updates to test files. The gcs.GetFolderRequest struct, along with StatObjectRequest and ListObjectsRequest, now includes a FetchFromCache boolean field. Review comments indicate that the FetchFromCache flag is not yet implemented for StatObject within fastStatBucket.StatObject and that fastStatBucket.ListObjects does not currently utilize caching for listings, prompting a need for further implementation or clarification on future plans.

[Tulsishah]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a FetchFromCache flag to give callers explicit control over using the stat cache, which is a useful feature for performance tuning and consistency. The changes are well-contained, primarily affecting the fastStatBucket and propagating the new request structs through various bucket wrappers.

My review focuses on the new caching logic in fast_stat_bucket.go. I've identified a couple of areas for improvement:

• A potential panic due to an unsafe type assertion in ListObjects.
• A minor formatting inconsistency in an error message.

The addition of extensive unit tests for the new caching scenarios is excellent and greatly improves confidence in the changes. Overall, this is a solid contribution.