chore(core/cbor): idempotencyToken handling for CborCodec

Author: kuhe

.changeset/gentle-dogs-protect.md

@@ -0,0 +1,5 @@
+---
+"@smithy/middleware-retry": patch
+---
+
+update uuid types version

.changeset/quiet-yaks-bathe.md

@@ -0,0 +1,5 @@
+---
+"@smithy/core": minor
+---
+
+handle idempotency token generation for CBOR protocol

packages/core/package.json

@@ -78,7 +78,9 @@
     "@smithy/util-middleware": "workspace:^",
     "@smithy/util-stream": "workspace:^",
     "@smithy/util-utf8": "workspace:^",
-    "tslib": "^2.6.2"
+    "@types/uuid": "^9.0.1",
+    "tslib": "^2.6.2",
+    "uuid": "^9.0.1"
   },
   "engines": {
     "node": ">=18.0.0"

packages/core/src/submodules/cbor/CborCodec.spec.ts

@@ -0,0 +1,57 @@
+import { NormalizedSchema, sim, struct } from "@smithy/core/schema";
+import { describe, expect, it } from "vitest";
+
+import { cbor } from "./cbor";
+import { CborCodec, CborShapeSerializer } from "./CborCodec";
+
+describe(CborShapeSerializer.name, () => {
+  const codec = new CborCodec();
+
+  const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+  const idempotencyTokenSchemas = [
+    NormalizedSchema.of(sim("", "StringWithTraits", 0, 0b0100)),
+    NormalizedSchema.of(sim("", "StringWithTraits", 0, { idempotencyToken: 1 })),
+  ];
+
+  const plainSchemas = [
+    NormalizedSchema.of(0),
+    NormalizedSchema.of(sim("", "StringWithTraits", 0, 0)),
+    NormalizedSchema.of(sim("", "StringWithTraits", 0, {})),
+  ];
+
+  const serializer = codec.createSerializer();
+
+  describe("serialization", () => {
+    it("should generate an idempotency token when the input for such a member is undefined", () => {
+      for (const idempotencyTokenSchema of idempotencyTokenSchemas) {
+        for (const plainSchema of plainSchemas) {
+          const objectSchema = struct(
+            "ns",
+            "StructWithIdempotencyToken",
+            0,
+            ["idempotencyToken", "plainString"],
+            [idempotencyTokenSchema, plainSchema]
+          );
+
+          serializer.write(objectSchema, {
+            idempotencyToken: undefined,
+            plainString: undefined,
+          });
+          expect(cbor.deserialize(serializer.flush())).toMatchObject({
+            idempotencyToken: UUID_V4,
+          });
+
+          serializer.write(objectSchema, {
+            idempotencyToken: undefined,
+            plainString: "abc",
+          });
+          expect(cbor.deserialize(serializer.flush())).toMatchObject({
+            idempotencyToken: UUID_V4,
+            plainString: /^abc$/,
+          });
+        }
+      }
+    });
+  });
+});

packages/core/src/submodules/cbor/CborCodec.ts

@@ -1,5 +1,5 @@
 import { NormalizedSchema } from "@smithy/core/schema";
-import { parseEpochTimestamp } from "@smithy/core/serde";
+import { generateIdempotencyToken, parseEpochTimestamp } from "@smithy/core/serde";
 import { Codec, Schema, SerdeFunctions, ShapeDeserializer, ShapeSerializer } from "@smithy/types";
 
 import { cbor } from "./cbor";
@@ -52,10 +52,14 @@ export class CborShapeSerializer implements ShapeSerializer {
 
     switch (typeof source) {
       case "undefined":
+        if (ns.isIdempotencyToken()) {
+          return generateIdempotencyToken();
+        }
         return null;
       case "boolean":
       case "number":
       case "string":
+        return source;
       case "bigint":
       case "symbol":
         return source;

packages/core/src/submodules/schema/schemas/NormalizedSchema.spec.ts

@@ -214,4 +214,29 @@ describe(NormalizedSchema.name, () => {
       });
     });
   });
+
+  describe("idempotency token detection", () => {
+    const idempotencyTokenSchemas = [
+      NormalizedSchema.of(sim("", "StringWithTraits", 0, 0b0100)),
+      NormalizedSchema.of(sim("", "StringWithTraits", 0, { idempotencyToken: 1 })),
+    ];
+
+    const plainSchemas = [
+      NormalizedSchema.of(0),
+      NormalizedSchema.of(sim("", "StringWithTraits", 0, 0)),
+      NormalizedSchema.of(sim("", "StringWithTraits", 0, {})),
+    ];
+
+    it("has a consistent shortcut method for idempotencyToken detection", () => {
+      for (const schema of idempotencyTokenSchemas) {
+        expect(schema.isIdempotencyToken()).toBe(true);
+        expect(schema.getMergedTraits().idempotencyToken).toBe(1);
+      }
+
+      for (const schema of plainSchemas) {
+        expect(schema.isIdempotencyToken()).toBe(false);
+        expect(schema.getMergedTraits().idempotencyToken).toBe(undefined);
+      }
+    });
+  });
 });

packages/core/src/submodules/schema/schemas/NormalizedSchema.ts

@@ -273,6 +273,19 @@ export class NormalizedSchema implements INormalizedSchema {
     return this.getSchema() === SCHEMA.STREAMING_BLOB;
   }
 
+  /**
+   * This is a shortcut to avoid calling `getMergedTraits().idempotencyToken` on every string.
+   * @returns whether the schema has the idempotencyToken trait.
+   */
+  public isIdempotencyToken(): boolean {
+    if (typeof this.traits === "number") {
+      return (this.traits & 0b0100) === 0b0100;
+    } else if (typeof this.traits === "object") {
+      return !!this.traits.idempotencyToken;
+    }
+    return false;
+  }
+
   /**
    * @returns own traits merged with member traits, where member traits of the same trait key take priority.
    * This method is cached.

packages/core/src/submodules/serde/generateIdempotencyToken.spec.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test as it } from "vitest";
+
+import { generateIdempotencyToken } from "./generateIdempotencyToken";
+
+describe("generateIdempotencyToken", () => {
+  // This test is not meaningful when using uuid v4 as an external package, but
+  // will become useful if replacing the uuid implementation in the future.
+  const tokens = {} as Record<string, boolean>;
+
+  it("should repeatedly generate uuid v4 strings", () => {
+    for (let i = 0; i < 1000; ++i) {
+      const token = generateIdempotencyToken();
+      tokens[token] = true;
+      expect(generateIdempotencyToken()).toMatch(
+        /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+      );
+    }
+
+    expect(Object.keys(tokens)).toHaveLength(1000);
+  });
+});

packages/core/src/submodules/serde/generateIdempotencyToken.ts

@@ -0,0 +1,3 @@
+import { v4 as generateIdempotencyToken } from "uuid";
+
+export { generateIdempotencyToken };

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

@@ -1,5 +1,6 @@
 export * from "./copyDocumentWithTransform";
 export * from "./date-utils";
+export * from "./generateIdempotencyToken";
 export * from "./lazy-json";
 export * from "./parse-utils";
 export * from "./quote-header";