Fix kernel list cache compatibility detection for older libfuse runtimes

[syeleti-msft]

This change corrects how Blobfuse2 detects support for kernel directory-list caching.

Detects cache_readdir header availability without relying on misleading libfuse version macros.
Requires libfuse 3.16.1+ at runtime because earlier versions do not forward cache_readdir through the high-level opendir API.
Separately reports unsupported build headers, libfuse runtime, and kernel FUSE protocol.
Keeps release builds working with older libfuse versions while validating compatibility detection in CI.
Removes kernel list caching from sample configurations because most supported distributions do not currently provide a compatible libfuse runtime.
Documents the libfuse 3.16.1+ and Linux 5.1+/FUSE 7.28 requirements.
Stock Ubuntu 20.04, 22.04, and 24.04 remain supported, but kernel list caching is disabled there with an accurate warning.

Validation

FUSE2 and FUSE3 unit suites pass.
Compatibility probe passes with both libfuse 3.9 and 3.18.
Release pipeline YAML and sample configurations parse successfully.

[Copilot]

Pull request overview

This PR refines Blobfuse2’s kernel directory-list caching (“kernel list cache”) compatibility detection so the feature is enabled only when (a) build headers expose cache_readdir, (b) the loaded libfuse runtime actually forwards cache_readdir through the high-level opendir path, and (c) the kernel negotiates a sufficiently new FUSE protocol. It also updates CI and sample configs to reflect the tightened runtime requirements and typical distro availability.

Changes:

• Add a small C compatibility/probe utility and CI step to validate the libfuse runtime forwarding boundary (3.16.1+).
• Update libfuse wrapper/handler logic to distinguish unsupported headers vs unsupported libfuse runtime vs unsupported kernel FUSE protocol, with clearer warnings.
• Remove kernel list cache from sample configs and document the runtime/kernel requirements in config help and templates.

Reviewed changes

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

Show a summary per file

File	Description
tools/check_kernel_list_cache.c	New probe tool to validate libfuse runtime forwarding behavior and header availability.
component/libfuse/libfuse_compat.h	Adds version-string parsing helper used to gate runtime forwarding support.
component/libfuse/libfuse_wrapper.h	Changes compile-time detection for cache_readdir and updates kernel/runtime compatibility gating.
component/libfuse/libfuse_handler.go	Improves runtime/header/kernel-specific warning messages and disables kernel list cache when unsupported.
component/libfuse/libfuse_handler_test_wrapper.go	Adds a unit test covering kernel protocol minor-version gating (skips when unavailable).
component/libfuse/libfuse.go	Updates CLI flag help text to document runtime/kernel requirements.
setup/advancedConfig.yaml	Documents libfuse/FUSE protocol requirements next to the config knob.
sampleFileCacheConfig.yaml	Removes kernel-list-cache-expiration-sec from sample config to avoid enabling on common unsupported runtimes.
sampleFileCacheWithSASConfig.yaml	Same as above for SAS sample.
sampleBlockCacheConfig.yaml	Same as above for block cache sample.
azure-pipeline-templates/build-release.yml	Adds a fuse3-only CI step to compile/run the compatibility probe.
CHANGELOG.md	Documents the corrected compatibility detection behavior and requirements.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

component/libfuse/libfuse_wrapper.h:233

• kernel_supports_dir_cache currently requires conn->proto_major == 7. If a future kernel negotiates a higher FUSE protocol major (e.g., 8.x), this will incorrectly disable kernel list caching even though the feature should still be supported. It’s safer to treat any protocol major > 7 as new-enough, and only gate on minor when major == 7.

    if (!libfuse_version_supports_dir_cache(fuse_pkgversion()))
        return -2;

    return conn->proto_major == 7 && conn->proto_minor >= 28;
#endif

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

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