chore: add Storage#getBlobDescriptor skeleton

BenWhitehead · BenWhitehead · commit ec5907810936 · 2025-03-14T16:31:25.000-04:00
* Add BlobDescriptor interface
* Open up ByteRangeSpec to be public
* Add new Storage#getBlobDescriptor (currently throws UnsupportedOperationException)
* Add new integration test ITBlobDescriptorTest that attempts to read the final 13 bytes of an object as a `byte[]`
diff --git a/google-cloud-storage/clirr-ignored-differences.xml b/google-cloud-storage/clirr-ignored-differences.xml
@@ -120,4 +120,11 @@
     <method>* moveObject(*)</method>
   </difference>
 
+  <!-- Not breaking, new method has a default implementation -->
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/storage/Storage</className>
+    <method>com.google.api.core.ApiFuture getBlobDescriptor(com.google.cloud.storage.BlobId, com.google.cloud.storage.Storage$BlobSourceOption[])</method>
+  </difference>
+
 </differences>
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/BlobDescriptor.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/BlobDescriptor.java
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2024 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 com.google.api.core.ApiFuture;
+
+/** Blob Descriptor is to blob, what File Descriptor is to a file */
+public interface BlobDescriptor {
+
+  BlobInfo getBlobInfo();
+
+  ApiFuture<byte[]> readRangeAsBytes(ByteRangeSpec range);
+}
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/ByteRangeSpec.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/ByteRangeSpec.java
@@ -43,7 +43,7 @@
  */
 @InternalApi
 @ThreadSafe
-abstract class ByteRangeSpec implements Serializable {
+public abstract class ByteRangeSpec implements Serializable {
 
   public static final long EFFECTIVE_INFINITY = Long.MAX_VALUE;
 
@@ -111,19 +111,20 @@ public String toString() {
 
   protected abstract MoreObjects.ToStringHelper append(MoreObjects.ToStringHelper tsh);
 
-  static ByteRangeSpec nullRange() {
+  public static ByteRangeSpec nullRange() {
     return NullByteRangeSpec.INSTANCE;
   }
 
-  static ByteRangeSpec relativeLength(@Nullable Long beginOffset, @Nullable Long length) {
+  public static ByteRangeSpec relativeLength(@Nullable Long beginOffset, @Nullable Long length) {
     return create(beginOffset, length, RelativeByteRangeSpec::new);
   }
 
-  static ByteRangeSpec explicit(@Nullable Long beginOffset, @Nullable Long endOffsetExclusive) {
+  public static ByteRangeSpec explicit(
+      @Nullable Long beginOffset, @Nullable Long endOffsetExclusive) {
     return create(beginOffset, endOffsetExclusive, LeftClosedRightOpenByteRangeSpec::new);
   }
 
-  static ByteRangeSpec explicitClosed(
+  public static ByteRangeSpec explicitClosed(
       @Nullable Long beginOffset, @Nullable Long endOffsetInclusive) {
     return create(beginOffset, endOffsetInclusive, LeftClosedRightClosedByteRangeSpec::new);
   }
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/GrpcStorageImpl.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/GrpcStorageImpl.java
@@ -1448,6 +1448,12 @@ public Blob moveBlob(MoveBlobRequest request) {
         syntaxDecoders.blob);
   }
 
+  @Override
+  public ApiFuture<BlobDescriptor> getBlobDescriptor(BlobId id, BlobSourceOption... options) {
+    throw new UnsupportedOperationException(
+        fmtMethodName("getBlobDescriptor", BlobId.class, BlobSourceOption.class));
+  }
+
   @Override
   public GrpcStorageOptions getOptions() {
     return (GrpcStorageOptions) super.getOptions();
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java
@@ -22,6 +22,7 @@
 import static com.google.common.base.Preconditions.checkNotNull;
 import static java.util.Objects.requireNonNull;
 
+import com.google.api.core.ApiFuture;
 import com.google.api.core.BetaApi;
 import com.google.api.core.InternalApi;
 import com.google.api.core.InternalExtensionOnly;
@@ -5834,4 +5835,10 @@ default BlobWriteSession blobWriteSession(BlobInfo blobInfo, BlobWriteOption...
    */
   @TransportCompatibility({Transport.HTTP, Transport.GRPC})
   Blob moveBlob(MoveBlobRequest request);
+
+  @BetaApi
+  @TransportCompatibility({Transport.GRPC})
+  default ApiFuture<BlobDescriptor> getBlobDescriptor(BlobId id, BlobSourceOption... options) {
+    return throwGrpcOnly(fmtMethodName("getBlobDescriptor", BlobId.class, BlobSourceOption.class));
+  }
 }
diff --git a/google-cloud-storage/src/test/java/com/google/cloud/storage/ITBlobDescriptorTest.java b/google-cloud-storage/src/test/java/com/google/cloud/storage/ITBlobDescriptorTest.java
@@ -0,0 +1,98 @@
+/*
+ * Copyright 2024 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 static com.google.cloud.storage.TestUtils.xxd;
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.api.core.ApiFuture;
+import com.google.cloud.ReadChannel;
+import com.google.cloud.storage.TransportCompatibility.Transport;
+import com.google.cloud.storage.it.runner.StorageITRunner;
+import com.google.cloud.storage.it.runner.annotations.Backend;
+import com.google.cloud.storage.it.runner.annotations.Inject;
+import com.google.cloud.storage.it.runner.annotations.SingleBackend;
+import com.google.cloud.storage.it.runner.annotations.StorageFixture;
+import com.google.cloud.storage.it.runner.registry.Generator;
+import com.google.cloud.storage.it.runner.registry.ObjectsFixture;
+import com.google.cloud.storage.it.runner.registry.ObjectsFixture.ObjectAndContent;
+import com.google.common.io.ByteStreams;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.nio.channels.Channels;
+import java.nio.channels.WritableByteChannel;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import org.junit.Ignore;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+@RunWith(StorageITRunner.class)
+@SingleBackend(Backend.TEST_BENCH)
+@Ignore
+public final class ITBlobDescriptorTest {
+
+  private static final int _512KiB = 512 * 1024;
+
+  @Inject
+  @StorageFixture(Transport.GRPC)
+  public Storage storage;
+
+  @Inject public BucketInfo bucket;
+  @Inject public Generator generator;
+  @Inject public ObjectsFixture objectsFixture;
+
+  @Test
+  public void bytes() throws ExecutionException, InterruptedException, TimeoutException {
+    ObjectAndContent obj512KiB = objectsFixture.getObj512KiB();
+    BlobInfo info = obj512KiB.getInfo();
+    BlobId blobId = info.getBlobId();
+
+    BlobDescriptor blobDescriptor = storage.getBlobDescriptor(blobId).get(30, TimeUnit.SECONDS);
+
+    BlobInfo info1 = blobDescriptor.getBlobInfo();
+
+    assertThat(info1).isEqualTo(info);
+
+    ApiFuture<byte[]> futureRead1Bytes =
+        blobDescriptor.readRangeAsBytes(
+            ByteRangeSpec.explicit(_512KiB - 13L, ByteRangeSpec.EFFECTIVE_INFINITY));
+
+    byte[] read1Bytes = futureRead1Bytes.get(30, TimeUnit.SECONDS);
+    byte[] expected = obj512KiB.getContent().getBytes(_512KiB - 13);
+    assertThat(xxd(read1Bytes)).isEqualTo(xxd(expected));
+  }
+
+  @Test
+  public void readObject() throws IOException {
+    ObjectAndContent obj512KiB = objectsFixture.getObj512KiB();
+    BlobInfo info = obj512KiB.getInfo();
+    BlobId blobId = info.getBlobId();
+
+    byte[] expected = obj512KiB.getContent().getBytes(_512KiB - 13);
+    ByteArrayOutputStream baos = new ByteArrayOutputStream();
+    try (ReadChannel r = storage.reader(blobId);
+        WritableByteChannel w = Channels.newChannel(baos)) {
+      r.setChunkSize(0);
+      r.seek(_512KiB - 13);
+      ByteStreams.copy(r, w);
+    }
+
+    assertThat(xxd(baos.toByteArray())).isEqualTo(xxd(expected));
+  }
+}
diff --git a/google-cloud-storage/src/test/java/com/google/cloud/storage/it/ChecksummedTestContent.java b/google-cloud-storage/src/test/java/com/google/cloud/storage/it/ChecksummedTestContent.java
@@ -21,6 +21,7 @@
 import com.google.common.io.BaseEncoding;
 import com.google.common.primitives.Ints;
 import com.google.protobuf.ByteString;
+import com.google.protobuf.UnsafeByteOperations;
 import java.io.ByteArrayInputStream;
 import java.nio.charset.StandardCharsets;
 import java.util.Arrays;
@@ -42,6 +43,10 @@ public byte[] getBytes() {
     return bytes;
   }
 
+  public byte[] getBytes(int beginIndex) {
+    return UnsafeByteOperations.unsafeWrap(bytes).substring(beginIndex).toByteArray();
+  }
+
   public int getCrc32c() {
     return crc32c;
   }
diff --git a/google-cloud-storage/src/test/java/com/google/cloud/storage/it/runner/registry/AbstractStorageProxy.java b/google-cloud-storage/src/test/java/com/google/cloud/storage/it/runner/registry/AbstractStorageProxy.java
@@ -16,13 +16,15 @@
 
 package com.google.cloud.storage.it.runner.registry;
 
+import com.google.api.core.ApiFuture;
 import com.google.api.gax.paging.Page;
 import com.google.cloud.Policy;
 import com.google.cloud.ReadChannel;
 import com.google.cloud.WriteChannel;
 import com.google.cloud.storage.Acl;
 import com.google.cloud.storage.Acl.Entity;
 import com.google.cloud.storage.Blob;
+import com.google.cloud.storage.BlobDescriptor;
 import com.google.cloud.storage.BlobId;
 import com.google.cloud.storage.BlobInfo;
 import com.google.cloud.storage.BlobWriteSession;
@@ -489,6 +491,11 @@ public BlobWriteSession blobWriteSession(BlobInfo blobInfo, BlobWriteOption... o
     return delegate.blobWriteSession(blobInfo, options);
   }
 
+  @Override
+  public ApiFuture<BlobDescriptor> getBlobDescriptor(BlobId id, BlobSourceOption... options) {
+    return delegate.getBlobDescriptor(id, options);
+  }
+
   @Override
   public void close() throws Exception {
     delegate.close();
