refactor: Do not override user-provided agent

README.md

@@ -163,8 +163,10 @@ interface GaxiosOptions = {
   /**
    * An optional proxy to use for requests.
    * Available via `process.env.HTTP_PROXY` and `process.env.HTTPS_PROXY` as well - with a preference for the this config option when multiple are available.
+   * The `agent` option overrides this.
    *
    * @see {@link GaxiosOptions.noProxy}
+   * @see {@link GaxiosOptions.agent}
    */
   proxy?: string | URL;
   /**

src/common.ts

@@ -220,8 +220,10 @@ export interface GaxiosOptions {
   /**
    * An optional proxy to use for requests.
    * Available via `process.env.HTTP_PROXY` and `process.env.HTTPS_PROXY` as well - with a preference for the this config option when multiple are available.
+   * The {@link GaxiosOptions.agent `agent`} option overrides this.
    *
    * @see {@link GaxiosOptions.noProxy}
+   * @see {@link GaxiosOptions.agent}
    */
   proxy?: string | URL;
   /**

src/gaxios.ts

@@ -318,19 +318,20 @@ export class Gaxios {
     }
     opts.method = opts.method || 'GET';
 
-    const shouldUseProxy = this.#shouldUseProxyForURLIfAvailable(
-      opts.url,
-      opts.noProxy
-    );
-
     const proxy =
       opts.proxy ||
       process?.env?.HTTPS_PROXY ||
       process?.env?.https_proxy ||
       process?.env?.HTTP_PROXY ||
       process?.env?.http_proxy;
+    const urlMayUseProxy = this.#shouldUseProxyForURLIfAvailable(
+      opts.url,
+      opts.noProxy
+    );
 
-    if (shouldUseProxy && proxy) {
+    if (opts.agent) {
+      // don't do any of the following options - use the user-provided agent.
+    } else if (proxy && urlMayUseProxy) {
       const HttpsProxyAgent = await Gaxios.#getProxyAgent();
 
       if (this.agentCache.has(proxy)) {
@@ -344,7 +345,7 @@ export class Gaxios {
         this.agentCache.set(proxy, opts.agent);
       }
     } else if (opts.cert && opts.key) {
-      // Configure client for mTLS:
+      // Configure client for mTLS
       if (this.agentCache.has(opts.key)) {
         opts.agent = this.agentCache.get(opts.key);
       } else {