feat(core/protocols): make protocol selection easier (#1812)

Author: kuhe

.changeset/eighty-peas-think.md

@@ -0,0 +1,7 @@
+---
+"@smithy/smithy-client": minor
+"@smithy/types": minor
+"@smithy/core": minor
+---
+
+make protocol selection easier

packages/core/package.json

@@ -14,7 +14,9 @@
     "extract:docs": "api-extractor run --local",
     "test:cbor:perf": "node ./scripts/cbor-perf.mjs",
     "test": "yarn g:vitest run",
-    "test:watch": "yarn g:vitest watch"
+    "test:watch": "yarn g:vitest watch",
+    "test:integration": "yarn g:vitest run -c vitest.config.integ.mts",
+    "test:integration:watch": "yarn g:vitest watch -c vitest.config.integ.mts"
   },
   "main": "./dist-cjs/index.js",
   "module": "./dist-es/index.js",

packages/core/src/core.integ.spec.ts

@@ -0,0 +1,40 @@
+import { SmithyRpcV2CborProtocol } from "@smithy/core/cbor";
+import type { HttpProtocol } from "@smithy/core/protocols";
+import { RpcV2ProtocolClient } from "@smithy/smithy-rpcv2-cbor-schema";
+import { describe, expect, test as it } from "vitest";
+
+describe("@smithy/core", () => {
+  it("should normalize the config.protocol field", () => {
+    const withInstance = new RpcV2ProtocolClient({
+      endpoint: "https://localhost",
+      protocol: new SmithyRpcV2CborProtocol({
+        defaultNamespace: "smithy.protocoltests.rpcv2Cbor",
+      }),
+    });
+
+    expect(withInstance.config.protocol).toBeInstanceOf(SmithyRpcV2CborProtocol);
+    expect((withInstance.config.protocol as HttpProtocol).options.defaultNamespace).toEqual(
+      "smithy.protocoltests.rpcv2Cbor"
+    );
+
+    const withCtor = new RpcV2ProtocolClient({
+      endpoint: "https://localhost",
+      protocol: SmithyRpcV2CborProtocol,
+    });
+
+    expect(withCtor.config.protocol).toBeInstanceOf(SmithyRpcV2CborProtocol);
+    expect((withCtor.config.protocol as HttpProtocol).options.defaultNamespace).toEqual(
+      "smithy.protocoltests.rpcv2Cbor"
+    );
+
+    const withSettings = new RpcV2ProtocolClient({
+      endpoint: "https://localhost",
+      protocolSettings: {
+        defaultNamespace: "ns",
+      },
+    });
+
+    expect(withCtor.config.protocol).toBeInstanceOf(SmithyRpcV2CborProtocol);
+    expect((withSettings.config.protocol as HttpProtocol).options.defaultNamespace).toEqual("ns");
+  });
+});

packages/core/vitest.config.integ.mts

@@ -0,0 +1,10 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    exclude: ["**/*.{e2e,browser}.spec.ts"],
+    include: ["**/*.integ.spec.ts"],
+    environment: "node",
+    hideSkippedTests: true,
+  },
+});

packages/smithy-client/src/client.ts

@@ -1,6 +1,11 @@
+import { SerdeContext } from "@smithy/core/protocols";
 import { constructStack } from "@smithy/middleware-stack";
 import type {
+  $ClientProtocol,
+  $ClientProtocolCtor,
   Client as IClient,
+  ClientProtocol,
+  ClientProtocolCtor,
   Command,
   FetchHttpHandlerOptions,
   Handler,
@@ -14,17 +19,15 @@ import type {
  * @public
  */
 export interface SmithyConfiguration<HandlerOptions> {
+  /**
+   * @public
+   */
   requestHandler:
     | RequestHandler<any, any, HandlerOptions>
     | NodeHttpHandlerOptions
     | FetchHttpHandlerOptions
     | Record<string, unknown>;
-  /**
-   * The API version set internally by the SDK, and is
-   * not planned to be used by customer code.
-   * @internal
-   */
-  readonly apiVersion: string;
+
   /**
    * @public
    *
@@ -41,15 +44,51 @@ export interface SmithyConfiguration<HandlerOptions> {
    * and not needing middleware modifications between requests.
    */
   cacheMiddleware?: boolean;
+
+  /**
+   * A client request/response protocol or constructor of one.
+   * A protocol in this context is not e.g. https.
+   * It is the combined implementation of how to (de)serialize and create
+   * the messages (e.g. http requests/responses) that are being exchanged.
+   *
+   * @public
+   */
+  protocol?:
+    | ClientProtocol<any, any>
+    | $ClientProtocol<any, any>
+    | ClientProtocolCtor<any, any>
+    | $ClientProtocolCtor<any, any>;
+
+  /**
+   * These are automatically generated and will be passed to the
+   * config.protocol if given as a constructor.
+   * @internal
+   */
+  protocolSettings?: {
+    defaultNamespace?: string;
+    [setting: string]: unknown;
+  };
+
+  /**
+   * The API version set internally by the SDK, and is
+   * not planned to be used by customer code.
+   * @internal
+   */
+  readonly apiVersion: string;
 }
 
 /**
  * @internal
  */
 export type SmithyResolvedConfiguration<HandlerOptions> = {
   requestHandler: RequestHandler<any, any, HandlerOptions>;
-  readonly apiVersion: string;
   cacheMiddleware?: boolean;
+  protocol: ClientProtocol<any, any> | $ClientProtocol<any, any>;
+  protocolSettings?: {
+    defaultNamespace?: string;
+    [setting: string]: unknown;
+  };
+  readonly apiVersion: string;
 };
 
 /**
@@ -78,7 +117,15 @@ export class Client<
    */
   private handlers?: WeakMap<Function, Handler<any, any>> | undefined;
 
-  constructor(public readonly config: ResolvedClientConfiguration) {}
+  constructor(public readonly config: ResolvedClientConfiguration) {
+    const { protocol, protocolSettings } = config;
+    if (protocolSettings) {
+      if (typeof protocol === "function") {
+        // assumed to be a constructor
+        config.protocol = new (protocol as any)(protocolSettings);
+      }
+    }
+  }
 
   send<InputType extends ClientInput, OutputType extends ClientOutput>(
     command: Command<ClientInput, InputType, ClientOutput, OutputType, SmithyResolvedConfiguration<HandlerOptions>>,

packages/types/src/schema/schema-deprecated.ts

@@ -167,3 +167,11 @@ export interface ClientProtocol<Request, Response> extends ConfigurableSerdeCont
     response: Response
   ): Promise<Output>;
 }
+
+/**
+ * @public
+ * @deprecated use $ClientProtocolCtor.
+ */
+export interface ClientProtocolCtor<Request, Response> {
+  new (args: any): ClientProtocol<Request, Response>;
+}

packages/types/src/schema/schema.ts

@@ -277,6 +277,13 @@ export interface $ClientProtocol<Request, Response> extends ConfigurableSerdeCon
   ): Promise<Output>;
 }
 
+/**
+ * @public
+ */
+export interface $ClientProtocolCtor<Request, Response> {
+  new (args: any): $ClientProtocol<Request, Response>;
+}
+
 /**
  * Allows a protocol, codec, or serde utility to accept the serdeContext
  * from a client configuration or request/response handlerExecutionContext.

private/my-local-model-schema/src/XYZServiceClient.ts

@@ -36,14 +36,11 @@ import type {
   BodyLengthCalculator as __BodyLengthCalculator,
   CheckOptionalClientConfig as __CheckOptionalClientConfig,
   ChecksumConstructor as __ChecksumConstructor,
-  ClientProtocol,
   Decoder as __Decoder,
   Encoder as __Encoder,
   EventStreamSerdeProvider as __EventStreamSerdeProvider,
   HashConstructor as __HashConstructor,
   HttpHandlerOptions as __HttpHandlerOptions,
-  HttpRequest,
-  HttpResponse,
   Logger as __Logger,
   Provider as __Provider,
   StreamCollector as __StreamCollector,
@@ -175,16 +172,6 @@ export interface ClientDefaults extends Partial<__SmithyConfiguration<__HttpHand
    */
   extensions?: RuntimeExtension[];
 
-  /**
-   * The protocol controlling the message type (e.g. HTTP) and format (e.g. JSON)
-   * may be overridden. A default will always be set by the client.
-   * Available options depend on the service's supported protocols and will not be validated by
-   * the client.
-   * @alpha
-   *
-   */
-  protocol?: ClientProtocol<HttpRequest, HttpResponse>;
-
   /**
    * The function that provides necessary utilities for generating and parsing event stream
    */

private/my-local-model-schema/src/runtimeConfig.shared.ts

@@ -32,7 +32,10 @@ export const getRuntimeConfig = (config: XYZServiceClientConfig) => {
       },
     ],
     logger: config?.logger ?? new NoOpLogger(),
-    protocol: config?.protocol ?? new SmithyRpcV2CborProtocol({ defaultNamespace: "org.xyz.v1" }),
+    protocol: config?.protocol ?? SmithyRpcV2CborProtocol,
+    protocolSettings: config?.protocolSettings ?? {
+      defaultNamespace: "org.xyz.v1",
+    },
     urlParser: config?.urlParser ?? parseUrl,
     utf8Decoder: config?.utf8Decoder ?? fromUtf8,
     utf8Encoder: config?.utf8Encoder ?? toUtf8,

private/smithy-rpcv2-cbor-schema/src/RpcV2ProtocolClient.ts

@@ -31,13 +31,10 @@ import type {
   BodyLengthCalculator as __BodyLengthCalculator,
   CheckOptionalClientConfig as __CheckOptionalClientConfig,
   ChecksumConstructor as __ChecksumConstructor,
-  ClientProtocol,
   Decoder as __Decoder,
   Encoder as __Encoder,
   HashConstructor as __HashConstructor,
   HttpHandlerOptions as __HttpHandlerOptions,
-  HttpRequest,
-  HttpResponse,
   Logger as __Logger,
   Provider as __Provider,
   StreamCollector as __StreamCollector,
@@ -226,16 +223,6 @@ export interface ClientDefaults extends Partial<__SmithyConfiguration<__HttpHand
    */
   extensions?: RuntimeExtension[];
 
-  /**
-   * The protocol controlling the message type (e.g. HTTP) and format (e.g. JSON)
-   * may be overridden. A default will always be set by the client.
-   * Available options depend on the service's supported protocols and will not be validated by
-   * the client.
-   * @alpha
-   *
-   */
-  protocol?: ClientProtocol<HttpRequest, HttpResponse>;
-
   /**
    * The {@link @smithy/smithy-client#DefaultsMode} that will be used to determine how certain default configuration options are resolved in the SDK.
    */