Add sync() methods to HybridCache for consistency guarantees

[Barre]

Add sync(), remove_sync(), insert_sync(), and insert_with_properties_sync() methods to HybridCache to ensure operations complete before returning.

This fixes race conditions where:

• Deletions could be read after remove() due to async processing
• Overwrites could return stale data due to async deletion of old values

The new methods provide opt-in consistency guarantees without breaking existing code that doesn't require strict ordering.

What's changed and what's your intention?

Please explain IN DETAIL what the changes are in this PR and why they are needed. :D

Checklist

• [x] I have written the necessary rustdoc comments
• [x] I have added the necessary unit tests and integration tests
• [x] I have passed cargo x (or cargo x --fast instead if the old tests are not modified) in my local environment.

Related issues or PRs (optional)

https://github.com/foyer-rs/foyer/issues/1085

[MrCroxx]

Hi, @Barre . Thank you for your contribution.

I agree to expose the disk cache wait interface, but I have reservations about introducing interfaces like insert_sync()/delete_sync().

The issue here is that as a cache, foyer allows for the loss of any data. Therefore, the insert_sync() interface seems to be of little use.

The inconsistency issues you encountered with overwrite or deletion cannot be resolved solely through sync. I am working on fixing these issues. I hope to resolve this through other means rather than prematurely introducing additional interfaces that lead to complexity and confusion. For now, I can expose wait() for users with needs to call manually to address the issue.

However, it should be noted that this does not completely solve the problem, as the current design still cannot fully guarantee consistency for overwrite and deletion in order to prevent OOM and throttle the disk. Since most users of foyer use S3 as remote storage, these use cases are generally not involved, and I will gradually fix them in subsequent versions.

[codecov[bot]]

Codecov Report

:x: Patch coverage is 0% with 25 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
foyer/src/hybrid/cache.rs	0.00%	25 Missing :warning:

:exclamation: There is a different number of reports uploaded between BASE (e9f2c57) and HEAD (db9d1c8). Click for more details.

HEAD has 2 uploads less than BASE

Flag	BASE (e9f2c57)	HEAD (db9d1c8)
	3	1

Files with missing lines	Coverage Δ
foyer/src/hybrid/cache.rs	44.04% <0.00%> (-39.30%)	:arrow_down:

... and 53 files with indirect coverage changes

:rocket: New features to boost your workflow:

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