feat(gax): add rewindable stream buffer for chunk recovery

Introduce RewindableStreamBuffer managing a single-chunk buffer over an
InputStream, supporting forward compaction and topping up upon recovery
realignment without mark()/reset(). Enforces boundaries by throwing
FailedPreconditionException when a server offset is below the base
offset or beyond the current buffer window.

Use payloadLength in ChunkUploadRequest to avoid allocating temporary
byte arrays for full-sized chunks while reusing a single backing array.

Author: whowes

sdk-platform-java/gax-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/ResumableUploadChunkCallable.java

@@ -45,6 +45,7 @@
 import java.io.ByteArrayInputStream;
 import java.io.InputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
@@ -81,7 +82,12 @@ public Map<String, List<String>> getQueryParamNames(ChunkUploadRequest request)
 
                 @Override
                 public byte[] getBinaryRequestBody(ChunkUploadRequest request) {
-                  return request.getPayload();
+                  int length = request.getPayloadLength();
+                  byte[] payload = request.getPayload();
+                  if (length == payload.length) {
+                    return payload;
+                  }
+                  return Arrays.copyOf(payload, length);
                 }
 
                 @Override
@@ -110,7 +116,7 @@ private ResumableUploadChunkCallable(
   public ApiFuture<ChunkUploadResponse<ResponseT>> futureCall(
       ChunkUploadRequest request, @Nullable ApiCallContext inputContext) {
     Preconditions.checkNotNull(request);
-    boolean isPayloadEmpty = request.getPayload().length == 0;
+    boolean isPayloadEmpty = request.getPayloadLength() == 0;
     String command;
     if (request.isFinal()) {
       command = !isPayloadEmpty ? COMMAND_UPLOAD_FINALIZE : COMMAND_FINALIZE;

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/resumable/ChunkUploadRequest.java

@@ -32,6 +32,7 @@
 import com.google.api.core.BetaApi;
 import com.google.api.core.InternalApi;
 import com.google.auto.value.AutoValue;
+import com.google.common.base.Preconditions;
 import org.jspecify.annotations.NullMarked;
 
 /** Request value object for uploading a chunk to an active resumable upload session. */
@@ -48,6 +49,9 @@ public abstract class ChunkUploadRequest {
   @SuppressWarnings("mutable")
   public abstract byte[] getPayload();
 
+  /** The number of bytes within {@link #getPayload()} to upload. */
+  public abstract int getPayloadLength();
+
   /** The byte offset of this chunk in the overall stream. */
   public abstract long getOffset();
 
@@ -56,8 +60,12 @@ public abstract class ChunkUploadRequest {
 
   public abstract Builder toBuilder();
 
+  private static final int UNSET_PAYLOAD_LENGTH = Integer.MIN_VALUE;
+
   public static Builder newBuilder() {
-    return new AutoValue_ChunkUploadRequest.Builder().setFinal(false);
+    return new AutoValue_ChunkUploadRequest.Builder()
+        .setFinal(false)
+        .setPayloadLength(UNSET_PAYLOAD_LENGTH);
   }
 
   @AutoValue.Builder
@@ -66,10 +74,29 @@ public abstract static class Builder {
 
     public abstract Builder setPayload(byte[] payload);
 
+    public abstract Builder setPayloadLength(int payloadLength);
+
     public abstract Builder setOffset(long offset);
 
     public abstract Builder setFinal(boolean isFinal);
 
-    public abstract ChunkUploadRequest build();
+    abstract byte[] getPayload();
+
+    abstract int getPayloadLength();
+
+    abstract ChunkUploadRequest autoBuild();
+
+    public ChunkUploadRequest build() {
+      if (getPayloadLength() == UNSET_PAYLOAD_LENGTH) {
+        setPayloadLength(getPayload().length);
+      }
+      ChunkUploadRequest request = autoBuild();
+      Preconditions.checkArgument(
+          request.getPayloadLength() >= 0, "payloadLength must be non-negative");
+      Preconditions.checkArgument(
+          request.getPayloadLength() <= request.getPayload().length,
+          "payloadLength exceeds payload array length");
+      return request;
+    }
   }
 }

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/rpc/ResumableUploadChunkCoordinator.java

@@ -44,13 +44,11 @@
 import com.google.api.gax.retrying.RetrySettings;
 import com.google.api.gax.retrying.RetryingFuture;
 import com.google.api.gax.retrying.ScheduledRetryingExecutor;
-import com.google.common.io.ByteStreams;
 import com.google.common.util.concurrent.MoreExecutors;
 import com.google.errorprone.annotations.concurrent.GuardedBy;
 import java.io.IOException;
 import java.io.InputStream;
 import java.time.Duration;
-import java.util.Arrays;
 import java.util.concurrent.CancellationException;
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
@@ -75,22 +73,20 @@ final class ResumableUploadChunkCoordinator<ResponseT> {
           .setMaxAttempts(5)
           .build();
 
-  private static final byte[] EMPTY_PAYLOAD = new byte[0];
-
   private final Object lock = new Object();
 
   private final SettableApiFuture<ResponseT> result;
   private final ApiFuture<ResumableUploadSession> startFuture;
   private final UnaryCallable<ChunkUploadRequest, ChunkUploadResponse<ResponseT>>
       uploadChunkCallable;
   private final InputStream payload;
-  private final byte[] buffer;
   private final int chunkSize;
   private final ApiCallContext callContext;
   private final ClientContext clientContext;
   private final RetrySettings chunkRetrySettings;
 
   private volatile @Nullable String uploadSessionUrl;
+  private volatile @Nullable RewindableStreamBuffer buffer;
 
   @GuardedBy("lock")
   private boolean done;
@@ -120,7 +116,6 @@ final class ResumableUploadChunkCoordinator<ResponseT> {
     this.callContext = checkNotNull(callContext, "callContext must not be null");
     this.clientContext = checkNotNull(clientContext, "clientContext must not be null");
     this.chunkRetrySettings = DEFAULT_CHUNK_RETRY_SETTINGS;
-    this.buffer = new byte[chunkSize];
     synchronized (lock) {
       this.inFlightFuture = startFuture;
     }
@@ -138,6 +133,7 @@ public void onSuccess(ResumableUploadSession session) {
               }
             }
             uploadSessionUrl = session.getUploadUrl();
+            buffer = new RewindableStreamBuffer(payload, chunkSize, uploadSessionUrl);
             transmitChunk(0L);
           }
 
@@ -227,39 +223,42 @@ private void transmitChunk(long currentOffset) {
       }
     }
 
-    int bytesRead;
+    String url = uploadSessionUrl;
+    if (url == null) {
+      finish(null, new IllegalStateException("Upload session URL not available"));
+      return;
+    }
+
+    RewindableStreamBuffer streamBuffer = buffer;
+    if (streamBuffer == null) {
+      finish(null, new IllegalStateException("Upload buffer not initialized"));
+      return;
+    }
+
     try {
-      bytesRead = ByteStreams.read(payload, buffer, 0, chunkSize);
+      streamBuffer.fill(currentOffset);
     } catch (IOException e) {
       finish(null, e);
       return;
     }
 
-    boolean isFinal = bytesRead < chunkSize;
-    byte[] chunkPayload;
-    if (bytesRead == chunkSize) {
-      chunkPayload = buffer;
-    } else if (bytesRead == 0) {
-      chunkPayload = EMPTY_PAYLOAD;
+    UploadCommand command;
+    if (streamBuffer.isFinal()) {
+      command =
+          streamBuffer.isEmpty() ? UploadCommand.FINALIZE : UploadCommand.UPLOAD_FINALIZE;
     } else {
-      chunkPayload = Arrays.copyOf(buffer, bytesRead);
-    }
-
-    String url = uploadSessionUrl;
-    if (url == null) {
-      finish(null, new IllegalStateException("Upload session URL not available"));
-      return;
+      command = UploadCommand.UPLOAD;
     }
 
     ChunkUploadRequest chunkRequest =
         ChunkUploadRequest.newBuilder()
             .setUploadUrl(url)
-            .setPayload(chunkPayload)
-            .setOffset(currentOffset)
-            .setFinal(isFinal)
+            .setPayload(streamBuffer.getBuffer())
+            .setPayloadLength(streamBuffer.getPayloadLength())
+            .setOffset(streamBuffer.getBufferBaseOffset())
+            .setFinal(streamBuffer.isFinal())
             .build();
 
-    UploadCommand command = isFinal ? UploadCommand.UPLOAD_FINALIZE : UploadCommand.UPLOAD;
     ChunkAttemptCallable<ResponseT> attemptCallable =
         new ChunkAttemptCallable<>(
             uploadChunkCallable, chunkRequest, callContext, command);
@@ -277,7 +276,8 @@ private void transmitChunk(long currentOffset) {
     attemptCallable.setRetryingFuture(retryingFuture);
     setInFlightFuture(retryingFuture);
 
-    long chunkLength = chunkPayload.length;
+    long chunkLength = chunkRequest.getPayloadLength();
+    boolean isFinal = chunkRequest.isFinal();
     ApiFutures.addCallback(
         retryingFuture,
         new ApiFutureCallback<ChunkUploadResponse<ResponseT>>() {

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/rpc/RewindableStreamBuffer.java

@@ -0,0 +1,175 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google LLC nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.google.api.gax.rpc;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.common.io.ByteStreams;
+import java.io.IOException;
+import java.io.InputStream;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Manages a single-chunk buffer over an {@link InputStream} for resumable uploads.
+ *
+ * <p>The buffer holds at most one chunk of data in a reused backing array. It supports forward
+ * compaction and topping up upon recovery realignment, and enforces the boundary condition that
+ * requests to rewind before the buffer's base offset fail with an unrecoverable {@link
+ * FailedPreconditionException}.
+ */
+@NullMarked
+final class RewindableStreamBuffer {
+
+  private final InputStream inputStream;
+  private final int chunkSize;
+  private final String uploadUrl;
+  private final byte[] buffer;
+
+  private long bufferBaseOffset;
+  private int payloadLength;
+  private boolean isFinal;
+  private boolean streamExhausted;
+
+  RewindableStreamBuffer(InputStream inputStream, int chunkSize, String uploadUrl) {
+    this.inputStream = checkNotNull(inputStream, "inputStream must not be null");
+    checkArgument(chunkSize > 0, "chunkSize must be > 0");
+    this.chunkSize = chunkSize;
+    this.uploadUrl = checkNotNull(uploadUrl, "uploadUrl must not be null");
+    this.buffer = new byte[chunkSize];
+    this.bufferBaseOffset = 0L;
+    this.payloadLength = 0;
+    this.isFinal = false;
+    this.streamExhausted = false;
+  }
+
+  /**
+   * Advances the buffer from the stream starting at {@code targetOffset}, reading up to chunk size.
+   *
+   * @param targetOffset the absolute stream offset corresponding to the start of this chunk
+   * @throws IOException if reading from the stream fails
+   */
+  void fill(long targetOffset) throws IOException {
+    this.bufferBaseOffset = targetOffset;
+    this.payloadLength = ByteStreams.read(inputStream, buffer, 0, chunkSize);
+    this.isFinal = (payloadLength < chunkSize);
+    if (this.isFinal) {
+      this.streamExhausted = true;
+    }
+  }
+
+  /**
+   * Realigns the buffer window to {@code committedOffset}.
+   *
+   * <p>Compacts forward within the existing buffer to discard already-committed bytes, and then
+   * tops up the buffer to capacity from the underlying stream.
+   *
+   * @param committedOffset the server's committed byte offset
+   * @throws FailedPreconditionException if {@code committedOffset} is below the buffer's base
+   *     offset or beyond the current buffer window
+   * @throws IOException if reading from the stream fails
+   */
+  void realignTo(long committedOffset) throws IOException {
+    if (committedOffset < bufferBaseOffset) {
+      throw protocolViolation(
+          String.format(
+              "Server committed offset %d is below buffer base offset %d for upload URL %s; cannot"
+                  + " rewind stream before buffer base",
+              committedOffset, bufferBaseOffset, uploadUrl));
+    }
+
+    if (committedOffset > bufferBaseOffset + payloadLength) {
+      throw protocolViolation(
+          String.format(
+              "Server committed offset %d is beyond current buffer window [%d, %d] for upload URL"
+                  + " %s",
+              committedOffset, bufferBaseOffset, bufferBaseOffset + payloadLength, uploadUrl));
+    }
+
+    int committedWithinBuffer = (int) (committedOffset - bufferBaseOffset);
+    int remainingBytes = payloadLength - committedWithinBuffer;
+
+    if (remainingBytes > 0 && committedWithinBuffer > 0) {
+      System.arraycopy(buffer, committedWithinBuffer, buffer, 0, remainingBytes);
+    }
+
+    this.bufferBaseOffset = committedOffset;
+    this.payloadLength = remainingBytes;
+
+    if (!streamExhausted && payloadLength < chunkSize) {
+      int space = chunkSize - payloadLength;
+      int additionalRead = ByteStreams.read(inputStream, buffer, payloadLength, space);
+      payloadLength += additionalRead;
+      if (additionalRead < space) {
+        streamExhausted = true;
+      }
+    }
+
+    this.isFinal = streamExhausted;
+  }
+
+  byte[] getBuffer() {
+    return buffer;
+  }
+
+  int getPayloadLength() {
+    return payloadLength;
+  }
+
+  long getBufferBaseOffset() {
+    return bufferBaseOffset;
+  }
+
+  boolean isFinal() {
+    return isFinal;
+  }
+
+  boolean isEmpty() {
+    return payloadLength == 0;
+  }
+
+  private static final StatusCode FAILED_PRECONDITION_STATUS_CODE =
+      new StatusCode() {
+        @Override
+        public StatusCode.Code getCode() {
+          return StatusCode.Code.FAILED_PRECONDITION;
+        }
+
+        @Override
+        public @Nullable Object getTransportCode() {
+          return null;
+        }
+      };
+
+  static FailedPreconditionException protocolViolation(String message) {
+    return new FailedPreconditionException(message, null, FAILED_PRECONDITION_STATUS_CODE, false);
+  }
+}