[Do not Merge] POC for ACO

java-storage/google-cloud-storage/pom.xml

@@ -296,7 +296,6 @@
     <dependency>
       <groupId>com.google.api.grpc</groupId>
       <artifactId>proto-google-cloud-storage-control-v2</artifactId>
-      <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>com.google.cloud</groupId>

java-storage/google-cloud-storage/src/main/java/com/google/cloud/storage/AcoSpan.java

@@ -0,0 +1,169 @@
+/*
+ * 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.storage;
+
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.SpanContext;
+import io.opentelemetry.api.trace.StatusCode;
+import java.util.concurrent.TimeUnit;
+
+final class AcoSpan implements Span {
+  private final Span delegate;
+  private final String bucketName;
+  private final OtelStorageDecorator parent;
+
+  AcoSpan(Span delegate, String bucketName, OtelStorageDecorator parent) {
+    this.delegate = delegate;
+    this.bucketName = bucketName;
+    this.parent = parent;
+  }
+
+  private void applyCacheAttributes() {
+    if (bucketName != null && parent != null && parent.delegate instanceof StorageInternal) {
+      BucketMetadataCache.BucketMetadata md =
+          ((StorageInternal) parent.delegate).getBucketMetadataCache().get(bucketName);
+      if (md != null) {
+        delegate.setAttribute("gcp.resource.destination.id", md.resource);
+        delegate.setAttribute("gcp.resource.destination.location", md.location);
+      }
+    }
+  }
+
+  @Override
+  public void end() {
+    applyCacheAttributes();
+    delegate.end();
+  }
+
+  @Override
+  public void end(long timestamp, TimeUnit unit) {
+    applyCacheAttributes();
+    delegate.end(timestamp, unit);
+  }
+
+  @Override
+  public Span recordException(Throwable exception) {
+    delegate.recordException(exception);
+    if (exception instanceof StorageException
+        && parent != null
+        && parent.delegate instanceof StorageInternal) {
+      StorageException se = (StorageException) exception;
+      if (se.getCode() == 404) {
+        ((StorageInternal) parent.delegate).getBucketMetadataCache().remove(bucketName);
+      }
+    }
+    return this;
+  }
+
+  @Override
+  public Span recordException(Throwable exception, Attributes attributes) {
+    delegate.recordException(exception, attributes);
+    if (exception instanceof StorageException
+        && parent != null
+        && parent.delegate instanceof StorageInternal) {
+      StorageException se = (StorageException) exception;
+      if (se.getCode() == 404) {
+        ((StorageInternal) parent.delegate).getBucketMetadataCache().remove(bucketName);
+      }
+    }
+    return this;
+  }
+
+  @Override
+  public Span setAttribute(String k, String v) {
+    delegate.setAttribute(k, v);
+    return this;
+  }
+
+  @Override
+  public Span setAttribute(String k, long v) {
+    delegate.setAttribute(k, v);
+    return this;
+  }
+
+  @Override
+  public Span setAttribute(String k, double v) {
+    delegate.setAttribute(k, v);
+    return this;
+  }
+
+  @Override
+  public Span setAttribute(String k, boolean v) {
+    delegate.setAttribute(k, v);
+    return this;
+  }
+
+  @Override
+  public <T> Span setAttribute(AttributeKey<T> k, T v) {
+    delegate.setAttribute(k, v);
+    return this;
+  }
+
+  @Override
+  public Span addEvent(String n) {
+    delegate.addEvent(n);
+    return this;
+  }
+
+  @Override
+  public Span addEvent(String n, Attributes a) {
+    delegate.addEvent(n, a);
+    return this;
+  }
+
+  @Override
+  public Span addEvent(String n, long t, TimeUnit u) {
+    delegate.addEvent(n, t, u);
+    return this;
+  }
+
+  @Override
+  public Span addEvent(String n, Attributes a, long t, TimeUnit u) {
+    delegate.addEvent(n, a, t, u);
+    return this;
+  }
+
+  @Override
+  public Span setStatus(StatusCode c) {
+    delegate.setStatus(c);
+    return this;
+  }
+
+  @Override
+  public Span setStatus(StatusCode c, String d) {
+    delegate.setStatus(c, d);
+    return this;
+  }
+
+  @Override
+  public Span updateName(String name) {
+    delegate.updateName(name);
+    return this;
+  }
+
+  @Override
+  public SpanContext getSpanContext() {
+    return delegate.getSpanContext();
+  }
+
+  @Override
+  public boolean isRecording() {
+    return delegate.isRecording();
+  }
+}

java-storage/google-cloud-storage/src/main/java/com/google/cloud/storage/AcoSpanBuilder.java

@@ -0,0 +1,130 @@
+/*
+ * 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.storage;
+
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.SpanBuilder;
+import io.opentelemetry.api.trace.SpanContext;
+import io.opentelemetry.api.trace.SpanKind;
+import io.opentelemetry.context.Context;
+import java.util.concurrent.TimeUnit;
+
+final class AcoSpanBuilder implements SpanBuilder {
+  private final SpanBuilder delegate;
+  private final OtelStorageDecorator parent;
+  private String bucketName;
+
+  AcoSpanBuilder(SpanBuilder delegate, OtelStorageDecorator parent) {
+    this.delegate = delegate;
+    this.parent = parent;
+  }
+
+  @Override
+  public SpanBuilder setAttribute(String key, String value) {
+    delegate.setAttribute(key, value);
+    if ("gsutil.uri".equals(key) && value != null) {
+      String name = OtelStorageDecorator.extractBucketName(value);
+      if (name != null && !name.isEmpty()) {
+        this.bucketName = name;
+      }
+    }
+    return this;
+  }
+
+  @Override
+  public <T> SpanBuilder setAttribute(AttributeKey<T> key, T value) {
+    delegate.setAttribute(key, value);
+    if ("gsutil.uri".equals(key.getKey()) && value instanceof String) {
+      String name = OtelStorageDecorator.extractBucketName((String) value);
+      if (name != null && !name.isEmpty()) {
+        this.bucketName = name;
+      }
+    }
+    return this;
+  }
+
+  @Override
+  public Span startSpan() {
+    if (bucketName != null && parent != null && parent.delegate instanceof StorageInternal) {
+      parent.checkCacheAndTriggerFetch(bucketName);
+      BucketMetadataCache.BucketMetadata md =
+          ((StorageInternal) parent.delegate).getBucketMetadataCache().get(bucketName);
+      if (md != null) {
+        delegate.setAttribute("gcp.resource.destination.id", md.resource);
+        delegate.setAttribute("gcp.resource.destination.location", md.location);
+      }
+      return new AcoSpan(delegate.startSpan(), bucketName, parent);
+    }
+    return delegate.startSpan();
+  }
+
+  @Override
+  public SpanBuilder setNoParent() {
+    delegate.setNoParent();
+    return this;
+  }
+
+  @Override
+  public SpanBuilder setAttribute(String key, boolean value) {
+    delegate.setAttribute(key, value);
+    return this;
+  }
+
+  @Override
+  public SpanBuilder setAttribute(String key, double value) {
+    delegate.setAttribute(key, value);
+    return this;
+  }
+
+  @Override
+  public SpanBuilder setAttribute(String key, long value) {
+    delegate.setAttribute(key, value);
+    return this;
+  }
+
+  @Override
+  public SpanBuilder setSpanKind(SpanKind k) {
+    delegate.setSpanKind(k);
+    return this;
+  }
+
+  @Override
+  public SpanBuilder setStartTimestamp(long t, TimeUnit u) {
+    delegate.setStartTimestamp(t, u);
+    return this;
+  }
+
+  @Override
+  public SpanBuilder setParent(Context c) {
+    delegate.setParent(c);
+    return this;
+  }
+
+  @Override
+  public SpanBuilder addLink(SpanContext c) {
+    delegate.addLink(c);
+    return this;
+  }
+
+  @Override
+  public SpanBuilder addLink(SpanContext c, Attributes a) {
+    delegate.addLink(c, a);
+    return this;
+  }
+}

java-storage/google-cloud-storage/src/main/java/com/google/cloud/storage/BucketMetadataCache.java

@@ -0,0 +1,76 @@
+/*
+ * 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.storage;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+final class BucketMetadataCache {
+
+  static final class BucketMetadata {
+    final String resource;
+    final String location;
+
+    BucketMetadata(String resource, String location) {
+      this.resource = resource;
+      this.location = location;
+    }
+  }
+
+  private final Object lock = new Object();
+  private final Map<String, BucketMetadata> cache;
+
+  BucketMetadataCache(int capacity) {
+    this.cache =
+        new LinkedHashMap<String, BucketMetadata>(16, 0.75f, true) {
+          @Override
+          protected boolean removeEldestEntry(Map.Entry<String, BucketMetadata> eldest) {
+            return size() > capacity;
+          }
+        };
+  }
+
+  BucketMetadata get(String bucketName) {
+    synchronized (lock) {
+      return cache.get(bucketName);
+    }
+  }
+
+  void put(String bucketName, BucketMetadata metadata) {
+    synchronized (lock) {
+      cache.put(bucketName, metadata);
+    }
+  }
+
+  void remove(String bucketName) {
+    synchronized (lock) {
+      cache.remove(bucketName);
+    }
+  }
+
+  void clear() {
+    synchronized (lock) {
+      cache.clear();
+    }
+  }
+
+  boolean containsKey(String bucketName) {
+    synchronized (lock) {
+      return cache.containsKey(bucketName);
+    }
+  }
+}