feat: allow http(s).Agent ctor arg in lieu of instance

.changeset/fifty-ghosts-live.md

@@ -0,0 +1,6 @@
+---
+"@smithy/node-http-handler": minor
+"@smithy/types": minor
+---
+
+allow ctor args in lieu of Agent instances in node-http-handler ctor

packages/node-http-handler/src/node-http-handler.spec.ts

@@ -37,7 +37,22 @@ describe("NodeHttpHandler", () => {
       hRequestSpy.mockRestore();
       hsRequestSpy.mockRestore();
     });
+
     describe("constructor", () => {
+      it("allows https.Agent and http.Agent ctor args in place of actual instances", async () => {
+        const nodeHttpHandler = new NodeHttpHandler({
+          httpAgent: { maxSockets: 37 },
+          httpsAgent: { maxSockets: 39, keepAlive: false },
+        });
+
+        await nodeHttpHandler.handle({} as any);
+        expect(hRequestSpy.mock.calls[0][0]?.agent.maxSockets).toEqual(37);
+        expect(hRequestSpy.mock.calls[0][0]?.agent.keepAlive).toEqual(true);
+
+        expect((nodeHttpHandler as any).config.httpsAgent.maxSockets).toEqual(39);
+        expect((nodeHttpHandler as any).config.httpsAgent.keepAlive).toEqual(false);
+      });
+
       it.each([
         ["empty", undefined],
         ["a provider", async () => {}],

packages/node-http-handler/src/node-http-handler.ts

@@ -14,10 +14,7 @@ import { writeRequestBody } from "./write-request-body";
 
 export { NodeHttpHandlerOptions };
 
-interface ResolvedNodeHttpHandlerConfig {
-  requestTimeout?: number;
-  connectionTimeout?: number;
-  socketAcquisitionWarningTimeout?: number;
+interface ResolvedNodeHttpHandlerConfig extends Omit<NodeHttpHandlerOptions, "httpAgent" | "httpsAgent"> {
   httpAgent: hAgent;
   httpsAgent: hsAgent;
 }
@@ -118,8 +115,18 @@ export class NodeHttpHandler implements HttpHandler<NodeHttpHandlerOptions> {
     return {
       connectionTimeout,
       requestTimeout: requestTimeout ?? socketTimeout,
-      httpAgent: httpAgent || new hAgent({ keepAlive, maxSockets }),
-      httpsAgent: httpsAgent || new hsAgent({ keepAlive, maxSockets }),
+      httpAgent: (() => {
+        if (httpAgent instanceof hAgent || typeof (httpAgent as hAgent)?.destroy === "function") {
+          return httpAgent as hAgent;
+        }
+        return new hAgent({ keepAlive, maxSockets, ...httpAgent });
+      })(),
+      httpsAgent: (() => {
+        if (httpsAgent instanceof hsAgent || typeof (httpsAgent as hsAgent)?.destroy === "function") {
+          return httpsAgent as hsAgent;
+        }
+        return new hsAgent({ keepAlive, maxSockets, ...httpsAgent });
+      })(),
     };
   }
 

packages/types/src/http/httpHandlerInitialization.ts

@@ -1,5 +1,5 @@
-import type { Agent as hAgent } from "http";
-import type { Agent as hsAgent } from "https";
+import type { Agent as hAgent, AgentOptions as hAgentOptions } from "http";
+import type { Agent as hsAgent, AgentOptions as hsAgentOptions } from "https";
 
 /**
  *
@@ -51,8 +51,15 @@ export interface NodeHttpHandlerOptions {
    */
   socketTimeout?: number;
 
-  httpAgent?: hAgent;
-  httpsAgent?: hsAgent;
+  /**
+   * You can pass http.Agent or its constructor options.
+   */
+  httpAgent?: hAgent | hAgentOptions;
+
+  /**
+   * You can pass https.Agent or its constructor options.
+   */
+  httpsAgent?: hsAgent | hsAgentOptions;
 }
 
 /**