Bug fixes & Improvements

• Fixed memory leak in buffered reader during multi-block read PR#4638
• Improved direct patch enforcement strategy for gRPC client PR#4635

Dependency Upgrades / CVE fixes

• Upgraded Golang from 1.26.1 to 1.26.2 to include latest security patches and performance improvements.
• go-gRPC patch release upgrade from 1.79.2 to 1.79.3 to include latest security patches.

Consistent symlink handling across GCS clients

GCSFuse now represents symbolic links the same way as Storage Transfer Service (STS) and other GCS clients(like gcloud storage CLI etc). This feature makes it easier for customers to transfer data via GCSFuse to and from GCS without worrying about symbolic link compatibility issues across GCS clients. This is enabled by default.
GCSfuse will now represent the symbolic links as finite-sized objects where the content is the target path, identified by the reserved metadata goog-reserved-file-is-symlink: true. This new feature is compatible with old representation of symbolic links used by prior versions of GCSFuse.

Bug fixes & Improvements

• Enhanced resiliency of the writes(that includes checkpoint write) by increasing the retry deadline to a higher value(120s instead of 32s) PR#4473.
• Fixed a bug in the requester pays feature to ensure the billing project correctly propagates for ListObject requests in gRPC protocol, eliminating the "no user project provided" error PR#4611
• File Cache now adheres to the physical space utilization of files on the storage media rather than logical size PR#4514
• Fixed memory leak in buffered reader during multi-block read PR#4638
• Improved direct patch enforcement strategy for gRPC client PR#4635

Bugs Fixed

Premature EOF on kernels with large page-sizes
Aggressive kernel read-ahead on ARM64 architectures with large page-sizes previously caused premature-EOFs on reads. This release provides a critical stability fix for GCSFuse on ARM64 architectures configured with large page sizes (e.g. Google Cloud A4X and A4X Max instances with 64 KiB memory pages).

Built on top of version 3.6.0 with the following bug fixed

Premature EOF on kernels with large page-sizes
Aggressive kernel read-ahead on ARM64 architectures with large page-sizes previously caused premature-EOFs on reads. This release provides a critical stability fix for GCSFuse on ARM64 architectures configured with large page sizes (e.g. Google Cloud A4X and A4X Max instances with 64 KiB memory pages).

Bugs Fixed

• Premature EOF on kernels with large page-sizes
  Aggressive kernel read-ahead on ARM64 architectures with large page-sizes previously caused premature-EOFs on reads. This release provides a critical stability fix for GCSFuse on ARM64 architectures configured with large page sizes (e.g. Google Cloud A4X and A4X Max instances with 64 KiB memory pages).

Dependency Upgrades

• Upgraded Golang from 1.23.0 to 1.26.1 to include latest security patches and performance improvements.

Dependency Upgrades

• Upgraded Golang from 1.24.11 to 1.26.1 to include latest security patches and performance improvements.

Asynchronous Metadata Prefetching: Accelerate Metadata-Heavy Workloads

In this release, we are introducing an intelligent directory-aware asynchronous metadata prefetch mechanism designed to significantly reduce latency for file lookups by proactively populating the metadata cache. This feature also addresses performance degradation caused by cache evictions in large buckets by automatically "self-healing" the metadata cache when entries are missing or expired.

By fetching directory metadata in batches in the background, this feature can save approximately 20ms per file access and improve overall performance by up to 48% for metadata-intensive workloads like small file reads. Additionally, it offers massive cost efficiency by reducing GCS API calls (e.g., from 10,000 individual lookups to just 2 List calls for a 5,000-file directory), potentially lowering metadata access costs by over 90%.

• Feature Enablement: This feature is disabled by default in this release and can be enabled with the --enable-metadata-prefetch flag or metadata-cache:enable-metadata-prefetch config.
• Use Cases: Metadata-heavy workloads such as large-scale data processing with many small files and any scenarios where high directory locality is expected. Sample use cases include vision model building with many small image files or language models that work on crawled web data or Electronic Design Automation(EDA) simulation.
• Memory Usage: Memory consumption is bounded by the existing stat-cache-max-size-mb configuration (default: 34 MiB). Prefetch batches are limited to 5,000 entries (configurable) per directory to minimize memory/CPU pressure.
• CPU Usage: CPU consumption is typically lower when enabled due to the significant reduction in metadata network calls. Concurrent prefetch activity is strictly throttled by a global concurrency limit (10 by default; configurable) to prevent resource exhaustion.
• Large Directory Optimization: For directories with more than 5000 files, the system automatically switches to a Targeted Mode. Instead of fetching the entire directory, it only caches the immediate lexicographical siblings(up to 5K) of the accessed file, ensuring efficient scaling without excessive resource usage.

New Configuration Flags

The following flags can be used to configure this feature within the metadata-cache section of your configuration or as command-line arguments:

• enable-metadata-prefetch (bool)
  Enables background prefetching of metadata for objects within a directory during a cache miss. This feature performs a batch update to the metadata cache, significantly reducing latency for subsequent lookups of files in the directory.
  Default: False
• metadata-prefetch-entries-limit (Int)
  The maximum number of metadata entries (files and directories) to prefetch into the cache upon a prefetch trigger. Note that values higher than 5000 will trigger multiple sequential GCS List calls per directory, as a single call is capped at 5000 results.
  Default: 5000
• Metadata-prefetch-max-workers (Int)
  The maximum number of concurrent background workers allowed to perform metadata prefetching across all directories. Each directory is limited to one active worker at a time.
  Default: 10

Type cache deprecation

Starting with version 3.8.0, type cache is deprecated. Metadata cache will take care of serving type information (i.e, where it's a file or directory) now. All type-cache related flags such as enable-nonexistent-type-cache and type-cache-max-size-mb, are now no-op.

Reduced GCS Egress for Random Reads

Optimized initial read handling to reduce the initial egress. Previously, all initial requests were treated as sequential, triggering 200MB read requests. Now, initial requests with non-zero offsets are treated as random, utilizing a 1MB read requests.

Bug Fixes and Improvements

• A4X-Max has been added as a high-performance machine type.
• Histogram representations for metrics have been adjusted to focus on high latency cases by adjusting histogram boundaries. For eg, fs-op latencies more than 100ms would get adjusted in histogram to have more details than previous representation that truncates them.

Dependency Upgrades

• Upgraded Golang from 1.24.11 to 1.26.1 to include latest security patches and performance improvements.