sort map keys in JSON Document shape encodes (#599)

Author: lucix-aws

.changelog/ed10934bf38a4ea9a93df3498ffdfd8a.json

@@ -0,0 +1,8 @@
+{
+    "id": "ed10934b-f38a-4ea9-a93d-f3498ffdfd8a",
+    "type": "feature",
+    "description": "Sort map keys in JSON Document types.",
+    "modules": [
+        "."
+    ]
+}

document/json/encoder.go

@@ -4,6 +4,8 @@ import (
 	"fmt"
 	"math/big"
 	"reflect"
+	"slices"
+	"strings"
 
 	"github.com/aws/smithy-go/document"
 	"github.com/aws/smithy-go/document/internal/serde"
@@ -181,16 +183,25 @@ func (e *Encoder) encodeMap(vp valueProvider, rv reflect.Value) error {
 	object := vp.GetValue().Object()
 	defer object.Close()
 
-	for _, key := range rv.MapKeys() {
-		keyName := fmt.Sprint(key.Interface())
-		if keyName == "" {
+	rawKeys := rv.MapKeys()
+	keys := make([]*mapKey, 0, len(rawKeys))
+	for _, raw := range rawKeys {
+		keys = append(keys, &mapKey{
+			Value:      raw,
+			Underlying: fmt.Sprint(raw.Interface()),
+		})
+	}
+
+	slices.SortFunc(keys, sortMapKeys)
+	for _, key := range keys {
+		if key.Underlying == "" {
 			return &document.InvalidMarshalError{Message: "map key cannot be empty"}
 		}
 
-		ev := rv.MapIndex(key)
+		ev := rv.MapIndex(key.Value)
 		err := e.encode(jsonObjectKeyProvider{
 			Object: object,
-			Key:    keyName,
+			Key:    key.Underlying,
 		}, ev, serde.Tag{})
 		if err != nil {
 			return err
@@ -326,4 +337,15 @@ func isValidJSONNumber(s string) bool {
 
 	// Make sure we are at the end.
 	return s == ""
-}
+}
+
+// cache struct to cache a map key's reflect.Value with its underlying value,
+// since repeated calls to reflect.Value.Interface() may be expensive
+type mapKey struct {
+	Value      reflect.Value
+	Underlying string
+}
+
+func sortMapKeys(i, j *mapKey) int {
+	return strings.Compare(i.Underlying, j.Underlying)
+}

document/json/encoder_test.go

@@ -67,6 +67,32 @@ func TestNewEncoderUnsupportedTypes(t *testing.T) {
 	}
 }
 
+func TestDeterministicMapOrder(t *testing.T) {
+	value := struct {
+		Map map[string]string
+	}{
+		Map: map[string]string{
+			"foo": "bar",
+			"a":   "b",
+			"bar": "baz",
+			"b":   "c",
+			"baz": "qux",
+			"c":   "d",
+		},
+	}
+	expect := `{"Map":{"a":"b","b":"c","bar":"baz","baz":"qux","c":"d","foo":"bar"}}`
+
+	encoder := json.NewEncoder()
+	actual, err := encoder.Encode(value)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if expect != string(actual) {
+		t.Errorf("encode determinstic order:\n%q !=\n%q", expect, actual)
+	}
+}
+
 func testEncode(t *testing.T, tt testCase) {
 	t.Helper()
 

document/json/shared_test.go

@@ -27,6 +27,8 @@ type StructA struct {
 	FieldNestedStruct          *StructA `document:"field_nested_struct"`
 	FieldNestedStructOmitEmpty *StructA `document:"field_nested_struct_omit_empty,omitempty"`
 
+	FieldMap map[string]string `document:",omitempty"`
+
 	fieldUnexported string
 
 	StructB
@@ -88,6 +90,14 @@ var sharedObjectTests = map[string]testCase{
 	},
 	"filled json structure": {
 		json: []byte(`{
+  "FieldMap": {
+    "a": "b",
+    "bar": "baz",
+    "baz": "qux",
+    "c": "d",
+    "foo": "bar",
+    "z": "a"
+  },
   "FieldName": "a",
   "FieldPtrName": "b",
   "field_rename": "c",
@@ -115,6 +125,14 @@ var sharedObjectTests = map[string]testCase{
 			return &v
 		}(),
 		want: &StructA{
+			FieldMap: map[string]string{
+				"foo": "bar",
+				"bar": "baz",
+				"baz": "qux",
+				"a":   "b",
+				"c":   "d",
+				"z":   "a",
+			},
 			FieldName:            "a",
 			FieldPtrName:         ptr.String("b"),
 			FieldRename:          "c",