feat: add requestHandler ctor pass through type

Author: kuhe

.changeset/dry-balloons-smell.md

@@ -0,0 +1,5 @@
+---
+"@smithy/protocol-http": minor
+---
+
+add RequestHandlerParams type for ctor passthrough

.changeset/many-ads-float.md

@@ -0,0 +1,7 @@
+---
+"@smithy/fetch-http-handler": minor
+"@smithy/node-http-handler": minor
+"@smithy/protocol-http": minor
+---
+
+add static factory for http handlers

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

@@ -47,6 +47,19 @@ export class FetchHttpHandler implements HttpHandler<FetchHttpHandlerConfig> {
   private config?: FetchHttpHandlerConfig;
   private configProvider: Promise<FetchHttpHandlerConfig>;
 
+  /**
+   * @returns the input if it is an HttpHandler of any class,
+   * or instantiates a new instance of this handler.
+   */
+  public static create(instanceOrOptions?: HttpHandler<any> | FetchHttpHandlerConfig) {
+    if (typeof (instanceOrOptions as any)?.handle === "function") {
+      // is already an instance of HttpHandler.
+      return instanceOrOptions as HttpHandler<any>;
+    }
+    // input is ctor options or undefined.
+    return new FetchHttpHandler(instanceOrOptions as FetchHttpHandlerConfig);
+  }
+
   constructor(options?: FetchHttpHandlerOptions | Provider<FetchHttpHandlerOptions | undefined>) {
     if (typeof options === "function") {
       this.configProvider = options().then((opts) => opts || {});

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

@@ -57,6 +57,19 @@ export class NodeHttpHandler implements HttpHandler<NodeHttpHandlerOptions> {
   // Node http handler is hard-coded to http/1.1: https://github.com/nodejs/node/blob/ff5664b83b89c55e4ab5d5f60068fb457f1f5872/lib/_http_server.js#L286
   public readonly metadata = { handlerProtocol: "http/1.1" };
 
+  /**
+   * @returns the input if it is an HttpHandler of any class,
+   * or instantiates a new instance of this handler.
+   */
+  public static create(instanceOrOptions?: HttpHandler<any> | NodeHttpHandlerOptions) {
+    if (typeof (instanceOrOptions as any)?.handle === "function") {
+      // is already an instance of HttpHandler.
+      return instanceOrOptions as HttpHandler<any>;
+    }
+    // input is ctor options or undefined.
+    return new NodeHttpHandler(instanceOrOptions as NodeHttpHandlerOptions);
+  }
+
   constructor(options?: NodeHttpHandlerOptions | Provider<NodeHttpHandlerOptions | void>) {
     this.configProvider = new Promise((resolve, reject) => {
       if (typeof options === "function") {

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

@@ -49,6 +49,19 @@ export class NodeHttp2Handler implements HttpHandler<NodeHttp2HandlerOptions> {
 
   private readonly connectionManager: NodeHttp2ConnectionManager = new NodeHttp2ConnectionManager({});
 
+  /**
+   * @returns the input if it is an HttpHandler of any class,
+   * or instantiates a new instance of this handler.
+   */
+  public static create(instanceOrOptions?: HttpHandler<any> | NodeHttp2HandlerOptions) {
+    if (typeof (instanceOrOptions as any)?.handle === "function") {
+      // is already an instance of HttpHandler.
+      return instanceOrOptions as HttpHandler<any>;
+    }
+    // input is ctor options or undefined.
+    return new NodeHttp2Handler(instanceOrOptions as NodeHttp2HandlerOptions);
+  }
+
   constructor(options?: NodeHttp2HandlerOptions | Provider<NodeHttp2HandlerOptions | void>) {
     this.configProvider = new Promise((resolve, reject) => {
       if (typeof options === "function") {

packages/protocol-http/package.json

@@ -16,6 +16,13 @@
   "main": "./dist-cjs/index.js",
   "module": "./dist-es/index.js",
   "types": "./dist-types/index.d.ts",
+  "browser": {
+    "./dist-es/httpHandlerInitialization": "./dist-es/httpHandlerInitialization.browser"
+  },
+  "react-native": {
+    "./dist-es/httpHandlerInitialization": "./dist-es/httpHandlerInitialization.browser",
+    "./dist-cjs/httpHandlerInitialization": "./dist-cjs/httpHandlerInitialization.browser"
+  },
   "author": {
     "name": "AWS Smithy Team",
     "email": "",

packages/protocol-http/src/httpHandlerInitialization.browser.ts

@@ -0,0 +1,15 @@
+/**
+ * Alternate compilation for browser excluding http Agent types.
+ *
+ * @internal
+ */
+export type DefaultRequestHandlerInitializationPassThroughParameters = FetchHttpHandlerOptions;
+
+/**
+ * Copy of the options in @smithy/fetch-http-handler FetchHttpHandler class.
+ * Not imported due to dependency ordering.
+ */
+interface FetchHttpHandlerOptions {
+  requestTimeout?: number;
+  keepAlive?: boolean;
+}

packages/protocol-http/src/httpHandlerInitialization.ts

@@ -0,0 +1,35 @@
+import type { Agent as hAgent } from "http";
+import type { Agent as hsAgent } from "https";
+
+/**
+ *
+ * This type represents an alternate client constructor option for the entry
+ * "requestHandler". Instead of providing an instance of a requestHandler, the user
+ * may provide the requestHandler's constructor options for either the
+ * NodeHttpHandler or FetchHttpHandler.
+ *
+ * For other RequestHandlers, constructor parameter passthrough is not available.
+ *
+ * @public
+ */
+export type RequestHandlerParams = NodeHttpHandlerOptions | FetchHttpHandlerOptions;
+
+/**
+ * Copy of the options in @smithy/node-http-handler NodeHttpHandler class.
+ * Not imported due to dependency ordering.
+ */
+export interface NodeHttpHandlerOptions {
+  connectionTimeout?: number;
+  requestTimeout?: number;
+  httpAgent?: hAgent;
+  httpsAgent?: hsAgent;
+}
+
+/**
+ * Copy of the options in @smithy/fetch-http-handler FetchHttpHandler class.
+ * Not imported due to dependency ordering.
+ */
+export interface FetchHttpHandlerOptions {
+  requestTimeout?: number;
+  keepAlive?: boolean;
+}

packages/protocol-http/src/index.ts

@@ -2,6 +2,7 @@ export * from "./extensions";
 export * from "./Field";
 export * from "./Fields";
 export * from "./httpHandler";
+export * from "./httpHandlerInitialization";
 export * from "./httpRequest";
 export * from "./httpResponse";
 export * from "./isValidHostname";