test(gax): add showcase harness for resumable uploads

core/packages/gax/.gitignore

@@ -23,3 +23,4 @@ dist/
 *.tgz
 **/*.tgz
 test/showcase-echo-client/protos/protos.*
+test/showcase-resumable-upload/fixtures/protos/protos.*

core/packages/gax/client-libraries.md

@@ -149,6 +149,48 @@ in the second parameter:
 const [response] = await client.sampleMethod(request, options);
 ```
 
+### Resumable uploads
+
+Some APIs expose methods that upload large payloads through the resumable
+upload protocol. For these methods, the client method no
+longer returns the response directly; it returns a
+[`ResumableUpload`](https://googleapis.dev/nodejs/google-gax/latest/classes/ResumableUpload.html)
+helper. Call `start()` with a `NodeJS.ReadableStream` and await `finished()`
+for the final response:
+
+```ts
+const helper = await client.createResumableUpload(request);
+await helper.start({
+  uploadStream: dataStream,
+  chunkSize: 8 * 1024 * 1024, // 8MB chunks
+  onProgress: status => {
+    console.log(`Committed ${status.bytesUploaded} bytes to ${status.uploadUrl}`);
+  },
+});
+const response = await helper.finished();
+```
+
+The session URL is available as `helper.uploadUrl` once the upload has
+started. Save it if you need to resume the upload later — for example after a
+process crash or network drop. To resume, pass the saved URL to `start()` on a
+new helper, along with a fresh stream of the same payload:
+
+```ts
+const helper = await client.createResumableUpload();
+await helper.start({
+  uploadStream: dataStream,
+  resumeUrl: savedUploadUrl,
+});
+const response = await helper.finished();
+```
+
+The current implementation requires a seekable stream (for example, a file
+stream). Errors fall into three categories: transient errors (retried with
+exponential backoff), state mismatches (recovered by querying the server for
+the committed byte offset), and fatal errors (propagated to the caller).
+The whole session is bounded by a global deadline (10 minutes by default,
+scaled up for large payloads and overridable via `globalDeadlineMs`).
+
 ### Long-running operations
 
 Some methods are expected to run longer. They return an object of type

core/packages/gax/src/clientInterface.ts

@@ -25,6 +25,7 @@ import {
   PageDescriptor,
   StreamDescriptor,
 } from './descriptor';
+import {ResumableUploadDescriptor} from './resumableUpload';
 import * as longrunning from './longRunningCalls/longrunning';
 import * as operationProtos from '../protos/operations';
 
@@ -51,6 +52,7 @@ export interface Descriptors {
   stream: {[name: string]: StreamDescriptor};
   longrunning: {[name: string]: LongrunningDescriptor};
   batching?: {[name: string]: BundleDescriptor};
+  resumableUpload?: {[name: string]: ResumableUploadDescriptor};
 }
 
 export interface Callback<

core/packages/gax/src/descriptor.ts

@@ -31,3 +31,4 @@ export {LongRunningDescriptor as LongrunningDescriptor} from './longRunningCalls
 export {PageDescriptor} from './paginationCalls/pageDescriptor';
 export {StreamDescriptor} from './streamingCalls/streamDescriptor';
 export {BundleDescriptor} from './bundlingCalls/bundleDescriptor';
+export {ResumableUploadDescriptor} from './resumableUpload';

core/packages/gax/src/fallback.ts

@@ -55,6 +55,18 @@ export {
   PageDescriptor,
   StreamDescriptor,
 } from './descriptor';
+export {
+  ResumableUploadDescriptor,
+  ResumableUploadSession,
+  ResumableUploadState,
+  resumableUploadStub,
+} from './resumableUpload';
+export type {
+  ResumableUploadContext,
+  ResumableUploadProgress,
+  ResumableUploadStartParams,
+  ResumableSource,
+} from './resumableUpload';
 
 export {StreamType} from './streamingCalls/streaming';
 

core/packages/gax/src/gax.ts

@@ -19,6 +19,7 @@
  */
 
 import type {Message} from 'protobufjs';
+import type {ResumableUploadContext} from './resumableUpload';
 import {warn} from './warnings';
 import {GoogleError} from './googleError';
 import {BundleOptions} from './bundlingCalls/bundleExecutor';
@@ -172,6 +173,11 @@ export interface CallOptions {
   apiName?: string;
   retryRequestOptions?: RetryRequestOptions;
   enableTelemetryTracing?: boolean;
+  /**
+   * Internal context used by resumable upload methods. Populated by
+   * GAPIC-generated client libraries; do not set manually.
+   */
+  resumableUpload?: ResumableUploadContext;
 }
 
 export class CallSettings {
@@ -189,6 +195,7 @@ export class CallSettings {
   apiName?: string;
   retryRequestOptions?: RetryRequestOptions;
   enableTelemetryTracing?: boolean;
+  resumableUpload?: ResumableUploadContext;
 
   /**
    * @param {Object} settings - An object containing parameters of this settings.
@@ -223,6 +230,8 @@ export class CallSettings {
     this.apiName = settings.apiName ?? undefined;
     this.retryRequestOptions = settings.retryRequestOptions;
     this.enableTelemetryTracing = settings.enableTelemetryTracing;
+    this.resumableUpload =
+      'resumableUpload' in settings ? settings.resumableUpload : undefined;
   }
 
   /**
@@ -247,6 +256,7 @@ export class CallSettings {
     let apiName = this.apiName;
     let retryRequestOptions = this.retryRequestOptions;
     let enableTelemetryTracing = this.enableTelemetryTracing;
+    let resumableUpload = this.resumableUpload;
 
     // If the user provides a timeout to the method, that timeout value will be used
     // to override the backoff settings.
@@ -305,6 +315,9 @@ export class CallSettings {
     if ('enableTelemetryTracing' in options) {
       enableTelemetryTracing = options.enableTelemetryTracing;
     }
+    if ('resumableUpload' in options) {
+      resumableUpload = options.resumableUpload;
+    }
 
     return new CallSettings({
       timeout,
@@ -318,6 +331,7 @@ export class CallSettings {
       apiName,
       retryRequestOptions,
       enableTelemetryTracing,
+      resumableUpload,
     });
   }
 }

core/packages/gax/src/index.ts

@@ -36,6 +36,19 @@ export {
   PageDescriptor,
   StreamDescriptor,
 } from './descriptor';
+export {ResumableUploadDescriptor} from './resumableUpload';
+export {
+  ResumableUploadSession,
+  resumableUploadStub,
+  ResumableUploadState,
+} from './resumableUpload';
+export type {
+  ResumableUploadContext,
+  ResumableUploadProgress,
+  ResumableUploadStartParams,
+  ResumableSource,
+} from './resumableUpload';
+export {resumableSourceFromFile} from './resumableSourceFromFile';
 export {
   CallOptions,
   CallSettings,

core/packages/gax/src/resumableSourceFromFile.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright 2026 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.
+ */
+
+import {createReadStream} from 'fs';
+import {statSync} from 'fs';
+
+import {ResumableSource} from './resumableUpload';
+
+/**
+ * Creates a {@link ResumableSource} backed by a local file.
+ *
+ * This factory lives outside the fallback transport entrypoint so browser
+ * builds do not pull in the Node.js `fs` module. Generated clients should
+ * delegate to this function rather than constructing file streams directly.
+ */
+export function resumableSourceFromFile(filePath: string): ResumableSource {
+  const stat = statSync(filePath);
+  return {
+    size: stat.size,
+    getStream: (offset?: number) => {
+      const start = offset ?? 0;
+      if (start < 0 || start > stat.size) {
+        throw new RangeError(
+          `Invalid start offset ${start} for file of size ${stat.size}.`,
+        );
+      }
+      return createReadStream(filePath, {start});
+    },
+  };
+}