feat(core/protocols): runtime protocol classes

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,130 @@
+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 { 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,
+          },
+        },
+        {
+          async endpoint() {
+            return {
+              protocol: "https:",
+              hostname: "amazonaws.com",
+              path: "/",
+            };
+          },
+        } as any
+      );
+
+      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,8 @@
+import { describe, expect, test as it } from "vitest";
+
+describe("", () => {
+  it("placeholder", async () => {
+    void expect;
+    throw new Error("NYI");
+  });
+});

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,8 @@
+import { describe, expect, test as it } from "vitest";
+
+describe("", () => {
+  it("placeholder", async () => {
+    void expect;
+    throw new Error("NYI");
+  });
+});

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

@@ -0,0 +1,129 @@
+import { RpcProtocol } from "@smithy/core/protocols";
+import { deref, ErrorSchema, NormalizedSchema, SCHEMA, TypeRegistry } from "@smithy/core/schema";
+import {
+  EndpointBearer,
+  HandlerExecutionContext,
+  HttpRequest,
+  HttpResponse,
+  OperationSchema,
+  ResponseMetadata,
+  SerdeFunctions,
+  ShapeDeserializer,
+  ShapeSerializer,
+} from "@smithy/types";
+import { calculateBodyLength } from "@smithy/util-body-length-browser";
+
+import { JsonCodec } from "./JsonCodec";
+import { loadRestJsonErrorCode } from "./parseJsonBody";
+
+/**
+ * @alpha
+ */
+export abstract class AwsJsonRpcProtocol extends RpcProtocol {
+  protected serializer: ShapeSerializer<string | Uint8Array>;
+  protected deserializer: ShapeDeserializer<string | Uint8Array>;
+  private codec: JsonCodec;
+
+  protected constructor({ defaultNamespace }: { defaultNamespace: string }) {
+    super({
+      defaultNamespace,
+    });
+    this.codec = new JsonCodec({
+      timestampFormat: {
+        useTrait: true,
+        default: SCHEMA.TIMESTAMP_EPOCH_SECONDS,
+      },
+      jsonName: false,
+    });
+    this.serializer = this.codec.createSerializer();
+    this.deserializer = this.codec.createDeserializer();
+  }
+
+  public async serializeRequest<Input extends object>(
+    operationSchema: OperationSchema,
+    input: Input,
+    context: HandlerExecutionContext & SerdeFunctions & EndpointBearer
+  ): Promise<HttpRequest> {
+    const request = await super.serializeRequest(operationSchema, input, context);
+    if (!request.path.endsWith("/")) {
+      request.path += "/";
+    }
+    Object.assign(request.headers, {
+      "content-type": `application/x-amz-json-${this.getJsonRpcVersion()}`,
+      "x-amz-target":
+        (this.getJsonRpcVersion() === "1.0" ? `JsonRpc10.` : `JsonProtocol.`) +
+        NormalizedSchema.of(operationSchema).getName(),
+    });
+    if (deref(operationSchema.input) === "unit" || !request.body) {
+      request.body = "{}";
+    }
+    try {
+      request.headers["content-length"] = String(calculateBodyLength(request.body));
+    } catch (e) {}
+    return request;
+  }
+
+  public getPayloadCodec(): JsonCodec {
+    return this.codec;
+  }
+
+  protected abstract getJsonRpcVersion(): "1.1" | "1.0";
+
+  protected async handleError(
+    operationSchema: OperationSchema,
+    context: HandlerExecutionContext & SerdeFunctions,
+    response: HttpResponse,
+    dataObject: any,
+    metadata: ResponseMetadata
+  ): Promise<never> {
+    // loadRestJsonErrorCode is still used in JSON RPC.
+    const errorIdentifier = loadRestJsonErrorCode(response, dataObject) ?? "Unknown";
+
+    let namespace = this.options.defaultNamespace;
+    let errorName = errorIdentifier;
+    if (errorIdentifier.includes("#")) {
+      [namespace, errorName] = errorIdentifier.split("#");
+    }
+
+    const registry = TypeRegistry.for(namespace);
+    let errorSchema: ErrorSchema;
+    try {
+      errorSchema = registry.getSchema(errorIdentifier) as ErrorSchema;
+    } catch (e) {
+      const baseExceptionSchema = TypeRegistry.for("awssdkjs.synthetic." + namespace).getBaseException();
+      if (baseExceptionSchema) {
+        const ErrorCtor = baseExceptionSchema.ctor;
+        throw Object.assign(new ErrorCtor(errorName), dataObject);
+      }
+      throw new Error(errorName);
+    }
+
+    const ns = NormalizedSchema.of(errorSchema);
+    const message = dataObject.message ?? dataObject.Message ?? "Unknown";
+    const exception = new errorSchema.ctor(message);
+
+    const headerBindings = new Set<string>(
+      Object.values(NormalizedSchema.of(errorSchema).getMemberSchemas())
+        .map((schema) => {
+          return schema.getMergedTraits().httpHeader;
+        })
+        .filter(Boolean) as string[]
+    );
+    await this.deserializeHttpMessage(errorSchema, context, response, headerBindings, dataObject);
+    const output = {} as any;
+    for (const [name, member] of Object.entries(ns.getMemberSchemas())) {
+      const target = member.getMergedTraits().jsonName ?? name;
+      output[name] = this.codec.createDeserializer().readObject(member, dataObject[target]);
+    }
+
+    Object.assign(exception, {
+      $metadata: metadata,
+      $response: response,
+      $fault: ns.getMergedTraits().error,
+      message,
+      ...output,
+    });
+
+    throw exception;
+  }
+}