feat: Implement Cached and Lazy Executor Service for getFileInfo

CONFIGURATION.md

@@ -49,7 +49,6 @@ These parameters fine-tune the low-level data streaming behavior. They allow you
 | `analytics-core.adaptive-read.sequential-read-threshold` | Threshold for number of sequential reads to switch to sequential mode. | `3` |
 | `analytics-core.random-read.min-request-size` | Minimum request size for random reads. If the requested read size is smaller, it reads up to this size. | `131072` (128 KB) |
 
-
 ### Telemetry and Monitoring
 
 These settings enable the emission of deep internal metrics—such as cache hit rates, operational durations, and throughput—to local logging consoles or distributed OpenTelemetry backends like Google Cloud Monitoring.

client/src/main/java/com/google/cloud/gcs/analyticscore/client/FlatNamespaceStrategyImpl.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.gcs.analyticscore.client;
+
+final class FlatNamespaceStrategyImpl implements NamespaceStrategy {
+
+  private final GcsClient gcsClient;
+
+  FlatNamespaceStrategyImpl(GcsClient gcsClient) {
+    this.gcsClient = gcsClient;
+  }
+}

client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsClient.java

@@ -43,6 +43,8 @@ WritableByteChannel createWriteChannel(GcsItemId itemId, GcsWriteOptions options
   /** Fetches object metadata. */
   GcsItemInfo getGcsItemInfo(GcsItemId itemId) throws IOException;
 
+  boolean isHnsBucket(String bucketName) throws IOException;
+
   /** Close the client. */
   void close();
 }

client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsClientImpl.java

@@ -171,6 +171,11 @@ BucketProperties getBucketProperties(String bucketName) throws IOException {
     }
   }
 
+  @Override
+  public boolean isHnsBucket(String bucketName) throws IOException {
+    return getBucketProperties(bucketName).isHnsEnabled();
+  }
+
   @Override
   public void close() {
     try {

client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsFileSystemImpl.java

@@ -34,6 +34,7 @@
 import com.google.common.collect.ImmutableList;
 import com.google.common.util.concurrent.ThreadFactoryBuilder;
 import java.io.IOException;
+import java.io.UncheckedIOException;
 import java.net.URI;
 import java.nio.channels.WritableByteChannel;
 import java.util.Collections;
@@ -44,16 +45,44 @@
 
 public class GcsFileSystemImpl implements GcsFileSystem {
 
+  /**
+   * Status or list calls (e.g., getting file info or listing a directory) block on I/O. A core pool
+   * size of 2 allows basic concurrency without significant resource overhead.
+   */
+  private static final int CACHED_EXECUTOR_CORE_POOL_SIZE = 2;
+
+  /**
+   * Using a 30-second keep-alive enables efficient thread reuse during intermittent spikes in
+   * status and list requests, while ensuring rapid resource cleanup during periods of inactivity.
+   */
+  private static final int CACHED_EXECUTOR_KEEP_ALIVE_SECONDS = 30;
+
+  /**
+   * Status and list calls block on I/O. An unbounded maximum pool size, combined with a
+   * zero-capacity SynchronousQueue, ensures tasks are never queued and new threads are immediately
+   * allocated to handle concurrent operations.
+   */
+  private static final int CACHED_EXECUTOR_MAX_POOL_SIZE = Integer.MAX_VALUE;
+
+  /**
+   * The maximum amount of time in seconds to wait for background thread pools to gracefully
+   * terminate upon file system closure.
+   */
+  private static final int EXECUTOR_SHUTDOWN_TIMEOUT_SECONDS = 10;
+
   private final GcsClient gcsClient;
   private final GcsFileSystemOptions fileSystemOptions;
-  private final Supplier<ExecutorService> executorServiceSupplier;
-
+  private final Supplier<ExecutorService> readExecutorServiceSupplier;
+  private final Supplier<ExecutorService> listExecutorServiceSupplier;
   private final Telemetry telemetry;
   private final AnalyticsCacheManager cacheManager;
+  private final FlatNamespaceStrategyImpl flatStrategy;
+  private final HierarchicalNamespaceStrategyImpl hnsStrategy;
 
   public GcsFileSystemImpl(GcsFileSystemOptions fileSystemOptions) {
     this.fileSystemOptions = fileSystemOptions;
-    this.executorServiceSupplier = initializeExecutionServiceSupplier();
+    this.readExecutorServiceSupplier = initializeReadExecutionServiceSupplier();
+    this.listExecutorServiceSupplier = initializeListExecutionServiceSupplier();
     this.telemetry = createTelemetry(fileSystemOptions.getAnalyticsCoreTelemetryOptions());
     this.cacheManager = new AnalyticsCacheManager(fileSystemOptions.getGcsCacheOptions());
     this.gcsClient =
@@ -63,12 +92,17 @@ public GcsFileSystemImpl(GcsFileSystemOptions fileSystemOptions) {
             Collections.emptyMap(),
             recorder ->
                 new GcsClientImpl(
-                    fileSystemOptions.getGcsClientOptions(), executorServiceSupplier, telemetry));
+                    fileSystemOptions.getGcsClientOptions(),
+                    readExecutorServiceSupplier,
+                    telemetry));
+    this.flatStrategy = new FlatNamespaceStrategyImpl(this.gcsClient);
+    this.hnsStrategy = new HierarchicalNamespaceStrategyImpl(this.gcsClient);
   }
 
   public GcsFileSystemImpl(Credentials credentials, GcsFileSystemOptions fileSystemOptions) {
     this.fileSystemOptions = fileSystemOptions;
-    this.executorServiceSupplier = initializeExecutionServiceSupplier();
+    this.readExecutorServiceSupplier = initializeReadExecutionServiceSupplier();
+    this.listExecutorServiceSupplier = initializeListExecutionServiceSupplier();
     this.telemetry = createTelemetry(fileSystemOptions.getAnalyticsCoreTelemetryOptions());
     this.cacheManager = new AnalyticsCacheManager(fileSystemOptions.getGcsCacheOptions());
     this.gcsClient =
@@ -80,8 +114,10 @@ public GcsFileSystemImpl(Credentials credentials, GcsFileSystemOptions fileSyste
                 new GcsClientImpl(
                     credentials,
                     fileSystemOptions.getGcsClientOptions(),
-                    executorServiceSupplier,
+                    readExecutorServiceSupplier,
                     telemetry));
+    this.flatStrategy = new FlatNamespaceStrategyImpl(this.gcsClient);
+    this.hnsStrategy = new HierarchicalNamespaceStrategyImpl(this.gcsClient);
   }
 
   @VisibleForTesting
@@ -101,9 +137,36 @@ public GcsFileSystemImpl(Credentials credentials, GcsFileSystemOptions fileSyste
       AnalyticsCacheManager cacheManager) {
     this.gcsClient = gcsClient;
     this.fileSystemOptions = fileSystemOptions;
-    this.executorServiceSupplier = initializeExecutionServiceSupplier();
+    this.readExecutorServiceSupplier = initializeReadExecutionServiceSupplier();
+    this.listExecutorServiceSupplier = initializeListExecutionServiceSupplier();
     this.telemetry = telemetry;
     this.cacheManager = cacheManager;
+    this.flatStrategy = new FlatNamespaceStrategyImpl(this.gcsClient);
+    this.hnsStrategy = new HierarchicalNamespaceStrategyImpl(this.gcsClient);
+  }
+
+  @VisibleForTesting
+  NamespaceStrategy resolveStrategy(String bucketName) throws IOException {
+    checkNotNull(bucketName, "bucketName cannot be null");
+    if (!fileSystemOptions.isHnsApiEnabled()) {
+      return flatStrategy;
+    }
+
+    BucketProperties properties =
+        cacheManager.getBucketProperties(
+            bucketName,
+            name -> {
+              try {
+                return BucketProperties.create(gcsClient.isHnsBucket(name));
+              } catch (IOException e) {
+                throw new UncheckedIOException(e);
+              }
+            });
+
+    if (properties.isHnsEnabled()) {
+      return hnsStrategy;
+    }
+    return flatStrategy;
   }
 
   @Override
@@ -163,16 +226,39 @@ public AnalyticsCacheManager getCacheManager() {
     return cacheManager;
   }
 
+  @VisibleForTesting
+  FlatNamespaceStrategyImpl getFlatStrategy() {
+    return flatStrategy;
+  }
+
+  @VisibleForTesting
+  HierarchicalNamespaceStrategyImpl getHnsStrategy() {
+    return hnsStrategy;
+  }
+
   @Override
   public void close() {
-    ExecutorService executorService = executorServiceSupplier.get();
-    executorService.shutdown();
+    ExecutorService readExecutorService = readExecutorServiceSupplier.get();
+    ExecutorService listExecutorService = listExecutorServiceSupplier.get();
+    readExecutorService.shutdown();
+    listExecutorService.shutdown();
     try {
-      if (!executorService.awaitTermination(10, TimeUnit.SECONDS)) {
-        executorService.shutdownNow();
+      // Wait a total of LIST_EXECUTOR_SHUTDOWN_TIMEOUT_SECONDS for both thread pools to terminate.
+      long deadline =
+          System.nanoTime() + TimeUnit.SECONDS.toNanos(EXECUTOR_SHUTDOWN_TIMEOUT_SECONDS);
+      // First, wait for the read executor service to terminate.
+      if (!readExecutorService.awaitTermination(
+          EXECUTOR_SHUTDOWN_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {
+        readExecutorService.shutdownNow();
+      }
+      // Then, wait for the cached executor service to terminate, with the remaining time.
+      if (!listExecutorService.awaitTermination(
+          Math.max(0, deadline - System.nanoTime()), TimeUnit.NANOSECONDS)) {
+        listExecutorService.shutdownNow();
       }
     } catch (InterruptedException e) {
-      executorService.shutdownNow();
+      readExecutorService.shutdownNow();
+      listExecutorService.shutdownNow();
       Thread.currentThread().interrupt();
     }
     gcsClient.close();
@@ -206,7 +292,7 @@ static Telemetry createTelemetry(TelemetryOptions telemetryOptions) {
   }
 
   @VisibleForTesting
-  Supplier<ExecutorService> initializeExecutionServiceSupplier() {
+  Supplier<ExecutorService> initializeReadExecutionServiceSupplier() {
     return Suppliers.memoize(
         () ->
             new ThreadPoolExecutor(
@@ -220,4 +306,33 @@ Supplier<ExecutorService> initializeExecutionServiceSupplier() {
                     .setDaemon(true)
                     .build()));
   }
+
+  @VisibleForTesting
+  Supplier<ExecutorService> initializeListExecutionServiceSupplier() {
+    return Suppliers.memoize(
+        () -> {
+          if (fileSystemOptions.isListParallelEnabled()) {
+            return createCachedExecutor();
+          }
+          return new LazyExecutorService();
+        });
+  }
+
+  private static ExecutorService createCachedExecutor() {
+    ThreadPoolExecutor service =
+        new ThreadPoolExecutor(
+            /* corePoolSize= */ CACHED_EXECUTOR_CORE_POOL_SIZE,
+            /* maximumPoolSize= */ CACHED_EXECUTOR_MAX_POOL_SIZE,
+            /* keepAliveTime= */ CACHED_EXECUTOR_KEEP_ALIVE_SECONDS,
+            TimeUnit.SECONDS,
+            new java.util.concurrent.SynchronousQueue<>(),
+            new ThreadFactoryBuilder()
+                .setNameFormat("gcs-filesystem-cached-pool-%d")
+                .setDaemon(true)
+                .build());
+    // allowCoreThreadTimeOut needs to be enabled for cases where the encapsulating class does not
+    // properly shut down the executor, preventing thread leaks.
+    service.allowCoreThreadTimeOut(true);
+    return service;
+  }
 }

client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsFileSystemOptions.java

@@ -25,6 +25,8 @@ public abstract class GcsFileSystemOptions {
 
   private static final String READ_THREAD_COUNT_KEY = "analytics-core.read.thread.count";
   private static final String CLIENT_TYPE_KEY = "client.type";
+  private static final String HNS_API_ENABLED_KEY = "analytics-core.hierarchical.namespace.enable";
+  private static final String LIST_PARALLEL_ENABLED_KEY = "analytics-core.list.parallel.enabled";
 
   /** Cloud Storage client to use. */
   public enum ClientType {
@@ -43,12 +45,18 @@ public enum ClientType {
 
   public abstract TelemetryOptions getAnalyticsCoreTelemetryOptions();
 
+  public abstract boolean isHnsApiEnabled();
+
+  public abstract boolean isListParallelEnabled();
+
   public abstract Builder toBuilder();
 
   public static Builder builder() {
     return new AutoValue_GcsFileSystemOptions.Builder()
         .setReadThreadCount(16)
         .setClientType(ClientType.HTTP_CLIENT)
+        .setHnsApiEnabled(true)
+        .setListParallelEnabled(true)
         .setGcsClientOptions(GcsClientOptions.builder().build())
         .setGcsCacheOptions(GcsCacheOptions.builder().build())
         .setAnalyticsCoreTelemetryOptions(TelemetryOptions.builder().build());
@@ -65,6 +73,15 @@ public static GcsFileSystemOptions createFromOptions(
       optionsBuilder.setClientType(
           ClientType.valueOf(analyticsCoreOptions.get(prefix + CLIENT_TYPE_KEY)));
     }
+    if (analyticsCoreOptions.containsKey(prefix + HNS_API_ENABLED_KEY)) {
+      optionsBuilder.setHnsApiEnabled(
+          Boolean.parseBoolean(analyticsCoreOptions.get(prefix + HNS_API_ENABLED_KEY)));
+    }
+    if (analyticsCoreOptions.containsKey(prefix + LIST_PARALLEL_ENABLED_KEY)) {
+      optionsBuilder.setListParallelEnabled(
+          Boolean.parseBoolean(analyticsCoreOptions.get(prefix + LIST_PARALLEL_ENABLED_KEY)));
+    }
+
     optionsBuilder.setGcsClientOptions(
         GcsClientOptions.createFromOptions(analyticsCoreOptions, prefix));
     optionsBuilder.setGcsCacheOptions(
@@ -84,6 +101,10 @@ public abstract static class Builder {
 
     public abstract Builder setReadThreadCount(int readThreadCount);
 
+    public abstract Builder setHnsApiEnabled(boolean isHnsApiEnabled);
+
+    public abstract Builder setListParallelEnabled(boolean isListParallelEnabled);
+
     public abstract Builder setGcsClientOptions(GcsClientOptions gcsClientOptions);
 
     /** Sets the configuration options for the GCS caching layer. */

client/src/main/java/com/google/cloud/gcs/analyticscore/client/HierarchicalNamespaceStrategyImpl.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.gcs.analyticscore.client;
+
+final class HierarchicalNamespaceStrategyImpl implements NamespaceStrategy {
+  private final GcsClient gcsClient;
+
+  HierarchicalNamespaceStrategyImpl(GcsClient gcsClient) {
+    this.gcsClient = gcsClient;
+  }
+}