feat(core/protocols): runtime protocol classes (#7110)

Author: kuhe

packages/core/package.json

@@ -82,14 +82,18 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@aws-sdk/types": "*",
+    "@aws-sdk/xml-builder": "*",
     "@smithy/core": "^3.5.1",
     "@smithy/node-config-provider": "^4.1.3",
     "@smithy/property-provider": "^4.0.4",
     "@smithy/protocol-http": "^5.1.2",
     "@smithy/signature-v4": "^5.1.2",
     "@smithy/smithy-client": "^4.4.1",
     "@smithy/types": "^4.3.1",
+    "@smithy/util-base64": "^4.0.0",
+    "@smithy/util-body-length-browser": "^4.0.0",
     "@smithy/util-middleware": "^4.0.4",
+    "@smithy/util-utf8": "^4.0.0",
     "fast-xml-parser": "4.4.1",
     "tslib": "^2.6.2"
   },

packages/core/src/submodules/protocols/ConfigurableSerdeContext.ts

@@ -0,0 +1,12 @@
+import { ConfigurableSerdeContext, SerdeFunctions } from "@smithy/types";
+
+/**
+ * @internal
+ */
+export class SerdeContextConfig implements ConfigurableSerdeContext {
+  protected serdeContext?: SerdeFunctions;
+
+  public setSerdeContext(serdeContext: SerdeFunctions): void {
+    this.serdeContext = serdeContext;
+  }
+}

packages/core/src/submodules/protocols/common.ts

@@ -1,5 +1,5 @@
 import { collectBody } from "@smithy/smithy-client";
-import type { HttpResponse, SerdeContext } from "@smithy/types";
+import type { SerdeFunctions } from "@smithy/types";
 
-export const collectBodyString = (streamBody: any, context: SerdeContext): Promise<string> =>
+export const collectBodyString = (streamBody: any, context: SerdeFunctions): Promise<string> =>
   collectBody(streamBody, context).then((body) => context.utf8Encoder(body));

packages/core/src/submodules/protocols/index.ts

@@ -1,4 +1,17 @@
 export * from "./coercing-serializers";
+export * from "./json/AwsJson1_0Protocol";
+export * from "./json/AwsJson1_1Protocol";
+export * from "./json/AwsJsonRpcProtocol";
+export * from "./json/AwsRestJsonProtocol";
+export * from "./json/JsonCodec";
+export * from "./json/JsonShapeDeserializer";
+export * from "./json/JsonShapeSerializer";
 export * from "./json/awsExpectUnion";
 export * from "./json/parseJsonBody";
+export * from "./query/AwsEc2QueryProtocol";
+export * from "./query/AwsQueryProtocol";
+export * from "./xml/AwsRestXmlProtocol";
+export * from "./xml/XmlCodec";
+export * from "./xml/XmlShapeDeserializer";
+export * from "./xml/XmlShapeSerializer";
 export * from "./xml/parseXmlBody";

packages/core/src/submodules/protocols/json/AwsJson1_0Protocol.spec.ts

@@ -0,0 +1,123 @@
+import { map, op, SCHEMA, sim, struct } from "@smithy/core/schema";
+import { toBase64 } from "@smithy/util-base64";
+import { toUtf8 } from "@smithy/util-utf8";
+import { describe, expect, test as it } from "vitest";
+
+import { context } from "../test-schema.spec";
+import { AwsJson1_0Protocol } from "./AwsJson1_0Protocol";
+
+describe(AwsJson1_0Protocol.name, () => {
+  const json = {
+    string: "string",
+    number: 1234,
+    boolean: false,
+    blob: "AAAAAAAAAAA=",
+    timestamp: 0,
+  };
+  const schema = struct(
+    "ns",
+    "MyStruct",
+    0,
+    [...Object.keys(json)],
+    [SCHEMA.STRING, SCHEMA.NUMERIC, SCHEMA.BOOLEAN, SCHEMA.BLOB, SCHEMA.TIMESTAMP_DEFAULT]
+  );
+  const serdeContext = {
+    base64Encoder: toBase64,
+    utf8Encoder: toUtf8,
+  } as any;
+
+  describe("codec", () => {
+    it("serializes blobs and timestamps", () => {
+      const protocol = new AwsJson1_0Protocol({
+        defaultNamespace: "namespace",
+      });
+      protocol.setSerdeContext(serdeContext);
+      const codec = protocol.getPayloadCodec();
+      const serializer = codec.createSerializer();
+      const data = {
+        string: "string",
+        number: 1234,
+        boolean: false,
+        blob: new Uint8Array(8),
+        timestamp: new Date(0),
+      };
+      serializer.write(schema, data);
+      const serialized = serializer.flush();
+      expect(JSON.parse(serialized)).toEqual({
+        string: "string",
+        number: 1234,
+        boolean: false,
+        blob: "AAAAAAAAAAA=",
+        timestamp: 0,
+      });
+    });
+
+    it("deserializes blobs and timestamps", async () => {
+      const protocol = new AwsJson1_0Protocol({
+        defaultNamespace: "namespace",
+      });
+      protocol.setSerdeContext(serdeContext);
+      const codec = protocol.getPayloadCodec();
+      const deserializer = codec.createDeserializer();
+
+      const parsed = await deserializer.read(schema, JSON.stringify(json));
+      expect(parsed).toEqual({
+        string: "string",
+        number: 1234,
+        boolean: false,
+        blob: new Uint8Array(8),
+        timestamp: new Date(0),
+      });
+    });
+
+    it("ignores JSON name and HTTP bindings", async () => {
+      const protocol = new AwsJson1_0Protocol({
+        defaultNamespace: "namespace",
+      });
+      protocol.setSerdeContext(serdeContext);
+
+      const schema = struct(
+        "ns",
+        "MyHttpBindingStructure",
+        {},
+        ["header", "query", "headerMap", "payload"],
+        [
+          sim("ns", "MyHeader", SCHEMA.STRING, { httpHeader: "header", jsonName: "MyHeader" }),
+          sim("ns", "MyQuery", SCHEMA.STRING, { httpQuery: "query" }),
+          map(
+            "ns",
+            "HeaderMap",
+            {
+              httpPrefixHeaders: "",
+            },
+            SCHEMA.STRING,
+            SCHEMA.NUMERIC
+          ),
+          sim("ns", "MyPayload", SCHEMA.DOCUMENT, { httpPayload: 1 }),
+        ]
+      );
+      const operationSchema = op("ns", "MyOperation", {}, schema, "unit");
+
+      const request = await protocol.serializeRequest(
+        operationSchema,
+        {
+          header: "hello",
+          query: "world",
+          headerMap: {
+            a: 1,
+            b: 2,
+          },
+        },
+        context
+      );
+
+      expect(request.headers).toEqual({
+        "content-length": "60",
+        "content-type": "application/x-amz-json-1.0",
+        "x-amz-target": "JsonRpc10.MyOperation",
+      });
+      expect(request.query).toEqual({});
+      expect(request.body).toEqual(`{"header":"hello","query":"world","headerMap":{"a":1,"b":2}}`);
+    });
+  });
+});

packages/core/src/submodules/protocols/json/AwsJson1_0Protocol.ts

@@ -0,0 +1,21 @@
+import { AwsJsonRpcProtocol } from "./AwsJsonRpcProtocol";
+
+/**
+ * @alpha
+ * @see https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#differences-between-awsjson1-0-and-awsjson1-1
+ */
+export class AwsJson1_0Protocol extends AwsJsonRpcProtocol {
+  public constructor({ defaultNamespace }: { defaultNamespace: string }) {
+    super({
+      defaultNamespace,
+    });
+  }
+
+  public getShapeId(): string {
+    return "aws.protocols#awsJson1_0";
+  }
+
+  protected getJsonRpcVersion() {
+    return "1.0" as const;
+  }
+}

packages/core/src/submodules/protocols/json/AwsJson1_1Protocol.spec.ts

@@ -0,0 +1,77 @@
+import { HttpResponse } from "@smithy/protocol-http";
+import { describe, expect, test as it } from "vitest";
+
+import { context, deleteObjects } from "../test-schema.spec";
+import { AwsJson1_0Protocol } from "./AwsJson1_0Protocol";
+
+/**
+ * These tests are cursory since most coverage is provided by protocol tests.
+ */
+describe(AwsJson1_0Protocol, () => {
+  it("is 1.0", async () => {
+    const protocol = new AwsJson1_0Protocol({
+      defaultNamespace: "",
+    });
+    expect(protocol.getShapeId()).toEqual("aws.protocols#awsJson1_0");
+  });
+
+  it("serializes a request", async () => {
+    const protocol = new AwsJson1_0Protocol({
+      defaultNamespace: "",
+    });
+    const httpRequest = await protocol.serializeRequest(
+      deleteObjects,
+      {
+        Delete: {
+          Objects: [
+            {
+              Key: "key1",
+            },
+            {
+              Key: "key2",
+            },
+          ],
+        },
+      },
+      context
+    );
+
+    expect(httpRequest.method).toEqual("POST");
+    expect(httpRequest.body).toEqual(
+      JSON.stringify({
+        Delete: {
+          Objects: [
+            {
+              Key: "key1",
+            },
+            {
+              Key: "key2",
+            },
+          ],
+        },
+      })
+    );
+  });
+
+  it("deserializes a response", async () => {
+    const httpResponse = new HttpResponse({
+      statusCode: 200,
+      headers: {},
+    });
+
+    const protocol = new AwsJson1_0Protocol({
+      defaultNamespace: "",
+    });
+
+    const output = await protocol.deserializeResponse(deleteObjects, context, httpResponse);
+
+    expect(output).toEqual({
+      $metadata: {
+        httpStatusCode: 200,
+        requestId: undefined,
+        extendedRequestId: undefined,
+        cfId: undefined,
+      },
+    });
+  });
+});

packages/core/src/submodules/protocols/json/AwsJson1_1Protocol.ts

@@ -0,0 +1,21 @@
+import { AwsJsonRpcProtocol } from "./AwsJsonRpcProtocol";
+
+/**
+ * @alpha
+ * @see https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#differences-between-awsjson1-0-and-awsjson1-1
+ */
+export class AwsJson1_1Protocol extends AwsJsonRpcProtocol {
+  public constructor({ defaultNamespace }: { defaultNamespace: string }) {
+    super({
+      defaultNamespace,
+    });
+  }
+
+  public getShapeId(): string {
+    return "aws.protocols#awsJson1_1";
+  }
+
+  protected getJsonRpcVersion() {
+    return "1.1" as const;
+  }
+}

packages/core/src/submodules/protocols/json/AwsJsonRpcProtocol.spec.ts

@@ -0,0 +1,31 @@
+import { SCHEMA } from "@smithy/core/schema";
+import { describe, expect, test as it } from "vitest";
+
+import { AwsJsonRpcProtocol } from "./AwsJsonRpcProtocol";
+
+describe(AwsJsonRpcProtocol.name, () => {
+  it("has expected codec settings", async () => {
+    const protocol = new (class extends AwsJsonRpcProtocol {
+      constructor() {
+        super({ defaultNamespace: "" });
+      }
+
+      getShapeId(): string {
+        throw new Error("Method not implemented.");
+      }
+
+      protected getJsonRpcVersion(): "1.1" | "1.0" {
+        throw new Error("Method not implemented.");
+      }
+    })();
+
+    const codec = protocol.getPayloadCodec();
+    expect(codec.settings).toEqual({
+      jsonName: false,
+      timestampFormat: {
+        default: SCHEMA.TIMESTAMP_EPOCH_SECONDS,
+        useTrait: true,
+      },
+    });
+  });
+});