feat: Updated timeout Implementation and Documentation

[rhodgkins]

Is the timeout option used at all?

gaxios/src/common.ts

Line 180 in ef40c61

timeout?: number;

From a quick search and scan of the code I can't see how it's used? It's not an option in node-fetch either...

[danielbankhead]

It looks like it was passed to node-fetch v2 here:

gaxios/src/gaxios.ts

Lines 139 to 142 in 8490f24

	const fetchImpl = opts.fetchImplementation || fetch;
	const res = (await fetchImpl(opts.url!, opts)) as FetchResponse;
	const data = await this.getResponseData(opts, res);
	return this.translateResponse<T>(opts, res, data);

However, we should update this to work with any fetch implementation - I'll convert this to a feature request.

Implementation Notes

• All modern fetch implementations offer a signal param: https://developer.mozilla.org/en-US/docs/Web/API/fetch
• AbortSignal.timeout() looks like a good option: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static (note the unique TimeoutError thrown)
• We can combine the timeout abort signal with a user's abort signal with AbortSignal.any(): https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/any_static