chore: merge in new APIs

BEGIN_COMMIT_OVERRIDE
BEGIN_NESTED_COMMIT
feat: add @BetaApi Storage#blobReadSession for gRPC Transport

Add new BlobReadSession API to allow multiple reads from a single object version using the new BidiReadObject API.

There are two projections available publicly at this time: SeekableByteChannel and ScatteringByteChannel.

This new API is classified as a pre-GA feature and have breaking changes.

END_NESTED_COMMIT

BEGIN_NESTED_COMMIT
feat: add @BetaApi Storage#blobAppendableUpload for gRPC Transport

Add new BlobAppendableUpload API to allow appendable uploads using the new AppendableUploadSpec in BidiWriteObject API.

This new API is classified as a pre-GA feature and have breaking changes.

END_NESTED_COMMIT

BEGIN_NESTED_COMMIT
feat: implement improved retry context information

Prior to this change, retries were always wired into the request path, but no information about retries was included.

With this change all exceptions which lead to a terminal failure will be included as suppressed exceptions on the final exception.

```
com.google.cloud.storage.RetryContextTest$Invocation
	at com.google.cloud.storage.RetryContextTest.similarToRetryingHelper(RetryContextTest.java:377)
		... 29 more
	Suppressed: com.google.cloud.storage.RetryContext$RetryBudgetExhaustedComment: Operation failed to complete within attempt budget (attempts: 6, maxAttempts: 6, elapsed: PT0.39231668S, nextBackoff: PT0.4S, timeout: PT3.125S) previous failures follow in order of occurrence
	Suppressed: com.google.cloud.storage.RetryContextTest$Invocation
		... 29 more
		Suppressed: com.google.cloud.storage.RetryContext$BackoffComment: backing off PT0.0125S before next attempt
	Suppressed: com.google.cloud.storage.RetryContextTest$Invocation
		... 29 more
		Suppressed: com.google.cloud.storage.RetryContext$BackoffComment: backing off PT0.025S before next attempt
	Suppressed: com.google.cloud.storage.RetryContextTest$Invocation
		... 29 more
		Suppressed: com.google.cloud.storage.RetryContext$BackoffComment: backing off PT0.05S before next attempt
	Suppressed: com.google.cloud.storage.RetryContextTest$Invocation
		... 29 more
		Suppressed: com.google.cloud.storage.RetryContext$BackoffComment: backing off PT0.1S before next attempt
	Suppressed: com.google.cloud.storage.RetryContextTest$Invocation
		... 29 more
		Suppressed: com.google.cloud.storage.RetryContext$BackoffComment: backing off PT0.2S before next attempt
```
END_NESTED_COMMIT

END_COMMIT_OVERRIDE

Author: BenWhitehead

google-cloud-storage/clirr-ignored-differences.xml

@@ -120,4 +120,23 @@
     <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 blobReadSession(com.google.cloud.storage.BlobId, com.google.cloud.storage.Storage$BlobSourceOption[])</method>
+  </difference>
+
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/storage/Storage</className>
+    <method>com.google.cloud.storage.BlobAppendableUpload blobAppendableUpload(com.google.cloud.storage.BlobInfo, com.google.cloud.storage.BlobAppendableUploadConfig, com.google.cloud.storage.Storage$BlobWriteOption[])</method>
+  </difference>
+  <difference>
+    <differenceType>7005</differenceType>
+    <className>com/google/cloud/storage/Hasher$*</className>
+    <method>* validate(*)</method>
+    <to>* validate(*)</to>
+  </difference>
+
 </differences>

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

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2025 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.common.base.MoreObjects;
+import java.util.Objects;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+final class AndThenRangeSpecFunction extends RangeSpecFunction {
+
+  private final RangeSpecFunction first;
+  private final RangeSpecFunction second;
+
+  AndThenRangeSpecFunction(RangeSpecFunction first, RangeSpecFunction second) {
+    this.first = first;
+    this.second = second;
+  }
+
+  @Override
+  public RangeSpec apply(long offset, @Nullable RangeSpec prev) {
+    return second.apply(offset, first.apply(offset, prev));
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (!(o instanceof AndThenRangeSpecFunction)) {
+      return false;
+    }
+    AndThenRangeSpecFunction that = (AndThenRangeSpecFunction) o;
+    return Objects.equals(first, that.first) && Objects.equals(second, that.second);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(first, second);
+  }
+
+  @Override
+  public String toString() {
+    return MoreObjects.toStringHelper(this).add("first", first).add("second", second).toString();
+  }
+}

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

@@ -29,6 +29,8 @@
 import com.google.api.services.storage.Storage.Objects;
 import com.google.api.services.storage.Storage.Objects.Get;
 import com.google.api.services.storage.model.StorageObject;
+import com.google.cloud.storage.Conversions.Decoder;
+import com.google.cloud.storage.Retrying.Retrier;
 import com.google.cloud.storage.UnbufferedReadableByteChannelSession.UnbufferedReadableByteChannel;
 import com.google.cloud.storage.spi.v1.StorageRpc;
 import com.google.common.annotations.VisibleForTesting;
@@ -55,7 +57,6 @@
 import java.util.Locale;
 import java.util.Map;
 import java.util.Map.Entry;
-import java.util.function.Function;
 import javax.annotation.concurrent.Immutable;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
@@ -65,8 +66,8 @@ class ApiaryUnbufferedReadableByteChannel implements UnbufferedReadableByteChann
   private final ApiaryReadRequest apiaryReadRequest;
   private final Storage storage;
   private final SettableApiFuture<StorageObject> result;
-  private final HttpStorageOptions options;
   private final ResultRetryAlgorithm<?> resultRetryAlgorithm;
+  private final Retrier retrier;
 
   private long position;
   private ScatteringByteChannel sbc;
@@ -80,12 +81,12 @@ class ApiaryUnbufferedReadableByteChannel implements UnbufferedReadableByteChann
       ApiaryReadRequest apiaryReadRequest,
       Storage storage,
       SettableApiFuture<StorageObject> result,
-      HttpStorageOptions options,
+      Retrier retrier,
       ResultRetryAlgorithm<?> resultRetryAlgorithm) {
     this.apiaryReadRequest = apiaryReadRequest;
     this.storage = storage;
     this.result = result;
-    this.options = options;
+    this.retrier = retrier;
     this.resultRetryAlgorithm =
         new BasicResultRetryAlgorithm<Object>() {
           @Override
@@ -113,7 +114,7 @@ public long read(ByteBuffer[] dsts, int offset, int length) throws IOException {
     long totalRead = 0;
     do {
       if (sbc == null) {
-        sbc = Retrying.run(options, resultRetryAlgorithm, this::open, Function.identity());
+        sbc = retrier.run(resultRetryAlgorithm, this::open, Decoder.identity());
       }
 
       long totalRemaining = Buffers.totalRemaining(dsts, offset, length);

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

@@ -17,9 +17,8 @@
 package com.google.cloud.storage;
 
 import com.google.api.core.SettableApiFuture;
-import com.google.api.gax.retrying.ResultRetryAlgorithm;
 import com.google.api.services.storage.model.StorageObject;
-import com.google.cloud.storage.Retrying.RetryingDependencies;
+import com.google.cloud.storage.Retrying.RetrierWithAlg;
 import com.google.cloud.storage.UnbufferedWritableByteChannelSession.UnbufferedWritableByteChannel;
 import java.io.IOException;
 import java.nio.ByteBuffer;
@@ -42,12 +41,11 @@ final class ApiaryUnbufferedWritableByteChannel implements UnbufferedWritableByt
 
   ApiaryUnbufferedWritableByteChannel(
       HttpClientContext httpClientContext,
-      RetryingDependencies deps,
-      ResultRetryAlgorithm<?> alg,
+      RetrierWithAlg retrier,
       JsonResumableWrite resumableWrite,
       SettableApiFuture<StorageObject> result,
       LongConsumer committedBytesCallback) {
-    this.session = ResumableSession.json(httpClientContext, deps, alg, resumableWrite);
+    this.session = ResumableSession.json(httpClientContext, retrier, resumableWrite);
     this.result = result;
     this.committedBytesCallback = committedBytesCallback;
     this.open = true;