googleapis · blakeli0 · Aug 12, 2026 · Aug 14, 2026
@@ -0,0 +1,73 @@
+/*
+ * 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 com.google.api.core.BetaApi;
+import com.google.common.base.Preconditions;
+
+/** Value object representing a chunk upload request. */
+@BetaApi
+public class ChunkUploadRequest {
+
+  private final String uploadUrl;
+  private final byte[] data;
+  private final long offset;
+  private final long totalSize;
+  private final boolean isLast;
+
+  public ChunkUploadRequest(
+      String uploadUrl, byte[] data, long offset, long totalSize, boolean isLast) {
+    this.uploadUrl = Preconditions.checkNotNull(uploadUrl);
+    this.data = Preconditions.checkNotNull(data);
+    this.offset = offset;
+    this.totalSize = totalSize;
+    this.isLast = isLast;
+  }
+
+  public String getUploadUrl() {
+    return uploadUrl;
+  }
+
+  public byte[] getData() {
+    return data;
+  }
+
+  public long getOffset() {
+    return offset;
+  }
+
+  public long getTotalSize() {
+    return totalSize;
+  }
+
+  public boolean isLast() {
+    return isLast;
+  }
+}
@@ -0,0 +1,55 @@
+/*
+ * 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 com.google.api.core.BetaApi;
+import javax.annotation.Nullable;
+
+/** Value object representing a chunk upload response. */
+@BetaApi
+public class ChunkUploadResponse {
+
+  private final long committedOffset;
+  @Nullable private final Object responseBody;
+
+  public ChunkUploadResponse(long committedOffset, @Nullable Object responseBody) {
+    this.committedOffset = committedOffset;
+    this.responseBody = responseBody;
+  }
+
+  public long getCommittedOffset() {
+    return committedOffset;
+  }
+
+  @Nullable
+  public Object getResponseBody() {
+    return responseBody;
+  }
+}
@@ -0,0 +1,76 @@
+/*
+ * 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 com.google.api.core.BetaApi;
+import com.google.auto.value.AutoValue;
+
+/**
+ * A settings class to configure a {@link ResumableUploadCallable} for executing resumable uploads.
+ * Encapsulates protocol options such as payload chunk size.
+ */
+@BetaApi
+@AutoValue
+public abstract class ResumableUploadCallSettings {
+  private static final int DEFAULT_CHUNK_SIZE = 8 * 1024 * 1024; // 8 MB
+
+  /** Returns the configured chunk size in bytes (defaults to 8 MB / 8,388,608 bytes). */
+  public abstract int getChunkSize();
+
+  /**
+   * Merges another {@code ResumableUploadCallSettings} instance with this one. Fields set in {@code
+   * other} override fields in this instance.
+   *
+   * @param other settings to overlay; may be {@code null}
+   * @return a new, resolved {@code ResumableUploadCallSettings} instance
+   */
+  public ResumableUploadCallSettings merge(ResumableUploadCallSettings other) {
+    if (other == null) {
+      return this;
+    }
+    return toBuilder().setChunkSize(other.getChunkSize()).build();
+  }
+
+  public abstract Builder toBuilder();
+
+  public static Builder newBuilder() {
+    return new AutoValue_ResumableUploadCallSettings.Builder().setChunkSize(DEFAULT_CHUNK_SIZE);
+  }
+
+  /** Builder for {@link ResumableUploadCallSettings}. */
+  @AutoValue.Builder
+  public abstract static class Builder {
+    public abstract Builder setChunkSize(int chunkSize);
+
+    public abstract int getChunkSize();
+
+    public abstract ResumableUploadCallSettings build();
+  }
+}
@@ -0,0 +1,128 @@
+/*
+ * 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 com.google.api.core.BetaApi;
+import com.google.common.base.Preconditions;
+import java.io.InputStream;
+import javax.annotation.Nullable;
+
+/**
+ * A ResumableUploadCallable is an API-transport-independent wrapper for the Resumable Upload
+ * protocol. Operates directly on the request object and input stream payload.
+ *
+ * @param <RequestT> request type
+ * @param <ResponseT> response type
+ */
+@BetaApi
+public class ResumableUploadCallable<RequestT, ResponseT> {
+
+  private final ResumableUploadClient resumableUploadClient;
+  @Nullable private final ResumableUploadCallSettings defaultCallSettings;
+
+  public ResumableUploadCallable(
+      ResumableUploadClient resumableUploadClient,
+      @Nullable ResumableUploadCallSettings defaultCallSettings) {
+    this.resumableUploadClient = Preconditions.checkNotNull(resumableUploadClient);
+    this.defaultCallSettings = defaultCallSettings;
+  }
+
+  public ResumableUploadCallable(ResumableUploadClient resumableUploadClient) {
+    this(resumableUploadClient, null);
+  }
+
+  /**
+   * Performs a new resumable upload asynchronously.
+   *
+   * @param request the request message
+   * @param payload the data payload input stream
+   * @param perRequestSettings call settings overrides; may be {@code null}
+   * @param context call context overrides; may be {@code null}
+   * @return future for tracking and controlling the upload
+   */
+  public ResumableUploadFuture<ResponseT> futureCall(
+      RequestT request,
+      InputStream payload,
+      ResumableUploadCallSettings perRequestSettings,
+      ApiCallContext context) {
+    Preconditions.checkNotNull(request);
+
+    ResumableUploadCallSettings activeSettings =
+        defaultCallSettings != null
+            ? defaultCallSettings.merge(perRequestSettings)
+            : perRequestSettings;
+
+    ResumableUploadFutureImpl<RequestT, ResponseT> future =
+        new ResumableUploadFutureImpl<>(
+            resumableUploadClient, request, payload, activeSettings, context);
+
+    future.start();
+    return future;
+  }
+
+  /**
+   * Resumes an existing resumable upload session asynchronously using a saved session URL.
+   *
+   * @param sessionUrl the upload session URL
+   * @param payload the data payload input stream
+   * @param perRequestSettings call settings overrides; may be {@code null}
+   * @param context call context overrides; may be {@code null}
+   * @return future for tracking and controlling the upload
+   */
+  public ResumableUploadFuture<ResponseT> resumeCall(
+      String sessionUrl,
+      InputStream payload,
+      ResumableUploadCallSettings perRequestSettings,
+      ApiCallContext context) {
+    Preconditions.checkNotNull(sessionUrl);
+
+    ResumableUploadCallSettings activeSettings =
+        defaultCallSettings != null
+            ? defaultCallSettings.merge(perRequestSettings)
+            : perRequestSettings;
+
+    ResumableUploadFutureImpl<RequestT, ResponseT> future =
+        new ResumableUploadFutureImpl<>(
+            resumableUploadClient, sessionUrl, payload, activeSettings, context);
+
+    future.start();
+    return future;
+  }
+
+  public ResumableUploadFuture<ResponseT> futureCall(
+      RequestT request, InputStream payload, ResumableUploadCallSettings settings) {
+    return futureCall(request, payload, settings, null);
+  }
+
+  public ResumableUploadFuture<ResponseT> resumeCall(
+      String sessionUrl, InputStream payload, ResumableUploadCallSettings settings) {
+    return resumeCall(sessionUrl, payload, settings, null);
+  }
+}
@@ -0,0 +1,46 @@
+/*
+ * 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 com.google.api.core.BetaApi;
+
+/**
+ * Low-level transport Service Provider Interface (SPI) for executing individual Scotty resumable
+ * upload operations (session initiation and chunk upload).
+ */
+@BetaApi
+public interface ResumableUploadClient {
+
+  /** Returns a UnaryCallable to initiate a new resumable upload session. */
+  <RequestT> UnaryCallable<RequestT, ResumableUploadSession> startUploadCallable();
+
+  /** Returns a UnaryCallable to upload a payload byte chunk to an active session URL. */
+  UnaryCallable<ChunkUploadRequest, ChunkUploadResponse> uploadChunkCallable();
+}