feat(gax): add ResumableUploadClient.startUpload() and supporting types

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

@@ -0,0 +1,48 @@
+/*
+ * 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.resumable;
+
+import com.google.api.core.InternalApi;
+import com.google.api.gax.rpc.UnaryCallable;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Client interface for executing low-level resumable upload operations.
+ *
+ * @param <RequestT> request type for starting an upload
+ * @param <ResponseT> response type of the upload operation
+ */
+@NullMarked
+@InternalApi
+public interface ResumableUploadClient<RequestT, ResponseT> {
+
+  /** Returns a {@link UnaryCallable} to initiate a resumable upload session. */
+  UnaryCallable<RequestT, ResumableUploadSession> startUploadCallable();
+}

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

@@ -0,0 +1,74 @@
+/*
+ * 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.resumable;
+
+import com.google.api.core.InternalApi;
+import com.google.auto.value.AutoValue;
+import org.jspecify.annotations.NullMarked;
+
+/** Represents the session metadata returned after starting a resumable upload. */
+@NullMarked
+@InternalApi
+@AutoValue
+public abstract class ResumableUploadSession {
+
+  private static final long DEFAULT_CHUNK_GRANULARITY = 1L;
+
+  /** Returns the server-provided URL to which data uploads are directed. */
+  public abstract String getUploadUrl();
+
+  /**
+   * Returns the server-mandated chunk granularity in bytes.
+   *
+   * <p>When specified by the server (via {@code X-Goog-Upload-Chunk-Granularity}), intermediate
+   * upload chunks must have a size and offset that are an exact multiple of this value (the final
+   * chunk may be smaller). If not specified by the server, this defaults to 1 byte, indicating no
+   * alignment or granularity requirements apply.
+   *
+   * @return the chunk granularity in bytes
+   */
+  public abstract long getChunkGranularity();
+
+  public abstract Builder toBuilder();
+
+  public static Builder newBuilder() {
+    return new AutoValue_ResumableUploadSession.Builder()
+        .setChunkGranularity(DEFAULT_CHUNK_GRANULARITY);
+  }
+
+  @AutoValue.Builder
+  public abstract static class Builder {
+    public abstract Builder setUploadUrl(String uploadUrl);
+
+    public abstract Builder setChunkGranularity(long chunkGranularity);
+
+    public abstract ResumableUploadSession build();
+  }
+}

sdk-platform-java/gax-java/gax/src/test/java/com/google/api/gax/resumable/ResumableUploadSessionTest.java

@@ -0,0 +1,62 @@
+/*
+ * 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.resumable;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import org.junit.jupiter.api.Test;
+
+class ResumableUploadSessionTest {
+
+  private static final String UPLOAD_URL = "https://storage.googleapis.com/upload/session/12345";
+
+  @Test
+  void build_withUploadUrl_setsDefaultChunkGranularity() {
+    ResumableUploadSession session =
+        ResumableUploadSession.newBuilder().setUploadUrl(UPLOAD_URL).build();
+
+    assertThat(session.getUploadUrl()).isEqualTo(UPLOAD_URL);
+    assertThat(session.getChunkGranularity()).isEqualTo(1L);
+  }
+
+  @Test
+  void build_withExplicitChunkGranularity_preservesGranularity() {
+    long customChunkGranularity = 256 * 1024L;
+
+    ResumableUploadSession session =
+        ResumableUploadSession.newBuilder()
+            .setUploadUrl(UPLOAD_URL)
+            .setChunkGranularity(customChunkGranularity)
+            .build();
+
+    assertThat(session.getUploadUrl()).isEqualTo(UPLOAD_URL);
+    assertThat(session.getChunkGranularity()).isEqualTo(customChunkGranularity);
+  }
+}