feat(gax): support resumable uploads

[feywind]

Adds the client-side implementation of the resumable upload protocol to google-gax.

What's here

• ResumableUploadDescriptor / ResumableUploadSession and the resumableUploadStub that generated clients wire into createApiCall
• resumableSourceFromFile, a seekable upload source backed by a local file
• CallOptions.resumableUpload, the transport context generated clients pass to the stub
• exports from index, fallback and descriptor, plus user documentation in client-libraries.md
• unit tests and a hermetic system test (real HTTP server, no credentials) covering the state machine, transient retries, recovery from state mismatches and resume from a saved session URL

onProgress callbacks may return void; the previous signature rejected the documented usage, which only logs progress.

Verification

• npx tsc -p . — no errors in the touched files
• npx mocha build/test/unit — 406 passing
• npx mocha build/test/system-test/resumableUpload.js — 2 passing

Nothing in existing behaviour changes: the new session is only reachable through the new descriptor and stub.

Related to: #9283

[gemini-code-assist]

Code Review

This pull request introduces support for the resumable upload protocol in the Google API Extensions (gax) library, adding a state machine to manage chunked uploads, retries, and session recovery, along with corresponding tests and documentation. Feedback highlights a critical runtime crash in the HTTP request handling due to an incorrect response type cast, which also requires updating mock responses in unit and system tests. Additionally, the host/port parsing regex should be improved to support IPv6 addresses, and manual edits to the auto-generated markdown documentation should be moved upstream to the generator templates.

[gemini-code-assist]

The this.context.auth.request method from google-auth-library returns a GaxiosResponse object, not a standard Response object. Casting it using as unknown as Response and calling response.arrayBuffer() will result in a runtime TypeError: response.arrayBuffer is not a function in production.

To fix this, change the responseType to 'arraybuffer' and read the buffered data directly from response.data instead of using 'stream' and trying to call .arrayBuffer().

Suggested change

	const response = (await this.context.auth.request({
	url,
	method: 'POST',
	headers,
	body:
	body === null || body === undefined
	? undefined
	: typeof body === 'string'
	? body
	: Buffer.from(body),
	signal: controller.signal,
	responseType: 'stream',
	timeout: this.params?.timeout ?? DEFAULT_PER_REQUEST_TIMEOUT_MS,
	validateStatus: () => true,
	})) as unknown as Response;
	const responseBody = Buffer.from(await response.arrayBuffer());
	const response = await this.context.auth.request({
	url,
	method: 'POST',
	headers,
	body:
	body === null || body === undefined
	? undefined
	: typeof body === 'string'
	? body
	: Buffer.from(body),
	signal: controller.signal,
	responseType: 'arraybuffer',
	timeout: this.params?.timeout ?? DEFAULT_PER_REQUEST_TIMEOUT_MS,
	validateStatus: () => true,
	});
	const responseBody = Buffer.from(response.data as ArrayBuffer);

[gemini-code-assist]

Since the implementation is updated to use responseType: 'arraybuffer' and read from response.data, the mock response in the unit tests should be updated to return a GaxiosResponse-like object with a data property containing the buffer, rather than a standard Response with arrayBuffer().

function resumableUploadResponse(
  status: number,
  headers: {[name: string]: string},
  body = '',
): any {
  const normalized: {[name: string]: string} = {};
  for (const [name, value] of Object.entries(headers)) {
    normalized[name.toLowerCase()] = value;
  }
  return {
    status,
    headers: normalized,
    data: Buffer.from(body),
  };
}

[gemini-code-assist]

Since the implementation is updated to use responseType: 'arraybuffer' and read from response.data, the fakeAuth.request mock in the system tests should be updated to return a GaxiosResponse-like object with a data property containing the buffer, rather than a standard Response from fetch.

const fakeAuth = {
  async request(opts: {
    url?: string;
    method?: string;
    headers?: {[name: string]: string};
    body?: string | Buffer;
    signal?: AbortSignal;
  }) {
    const res = await fetch(opts.url!, {
      method: opts.method,
      headers: opts.headers,
      body: opts.body,
      signal: opts.signal,
    });
    const arrayBuffer = await res.arrayBuffer();
    return {
      status: res.status,
      headers: Object.fromEntries(res.headers.entries()),
      data: Buffer.from(arrayBuffer),
    };
  },
};

[gemini-code-assist]

The regex ^(.*):(\d+)$ will incorrectly match IPv6 addresses that do not have a port but end with digits (e.g., 2001:db8::1234), treating the last segment as a port. To correctly parse the host and port, especially when IPv6 addresses are involved, use a regex that handles bracketed IPv6 hosts.

Suggested change

	const match = servicePath.match(/^(.*):(\d+)$/);
	if (match) {
	servicePath = match[1];
	servicePort = parseInt(match[2], 10);
	}
	const match = servicePath.match(/^(\[[^\]]+\]|[^:]+):(\d+)$/);
	if (match) {
	servicePath = match[1];
	servicePort = parseInt(match[2], 10);
	}

[gemini-code-assist]

Please do not manually edit auto-generated markdown files to make changes, as these edits will be overwritten during the next regeneration. Instead, apply the fix upstream in the generator or templates so that the documentation correctly states that the start() method takes a ResumableSource (via the uploadSource parameter) rather than a bare NodeJS.ReadableStream directly.

References

1. Do not manually edit auto-generated files to fix typos or make other changes, as these edits will be overwritten during the next regeneration. Instead, apply the fixes upstream in the generator or templates.

[gemini-code-assist]

Please do not manually edit auto-generated markdown files to make changes, as these edits will be overwritten during the next regeneration. Instead, apply the fix upstream in the generator or templates so that the example correctly uses uploadSource (of type ResumableSource) rather than uploadStream to avoid runtime errors.

References

1. Do not manually edit auto-generated files to fix typos or make other changes, as these edits will be overwritten during the next regeneration. Instead, apply the fixes upstream in the generator or templates.

[gemini-code-assist]

Please do not manually edit auto-generated markdown files to make changes, as these edits will be overwritten during the next regeneration. Instead, apply the fix upstream in the generator or templates so that the example correctly uses uploadSource (of type ResumableSource) rather than uploadStream to avoid runtime errors.

References

1. Do not manually edit auto-generated files to fix typos or make other changes, as these edits will be overwritten during the next regeneration. Instead, apply the fixes upstream in the generator or templates.