feat: implement serde for simple document type (#655)

Author: lucix-aws

runtime/runtime-core/common/src/aws/smithy/kotlin/runtime/smithy/Document.kt

@@ -14,6 +14,14 @@ sealed class Document {
      * Wraps a [kotlin.Number] of arbitrary precision.
      */
     data class Number(val value: kotlin.Number) : Document() {
+        init {
+            if (value is Double && !value.isFinite() || value is Float && !value.isFinite()) {
+                throw IllegalArgumentException(
+                    "a document number cannot be $value, as its value cannot be preserved across serde"
+                )
+            }
+        }
+
         override fun toString() = value.toString()
     }
 

runtime/runtime-core/common/src/aws/smithy/kotlin/runtime/smithy/DocumentBuilder.kt

@@ -29,6 +29,11 @@ class DocumentBuilder internal constructor() {
         content[this] = value ?: Document.Null
     }
 
+    infix fun String.to(@Suppress("UNUSED_PARAMETER") value: Nothing?) {
+        require(content[this] == null) { "Key $this is already registered in builder" }
+        content[this] = Document.Null
+    }
+
     class ListBuilder internal constructor() {
         val content: MutableList<Document> = mutableListOf()
 
@@ -40,6 +45,8 @@ class DocumentBuilder internal constructor() {
             content.add(if (value != null) Document(value) else Document.Null)
         fun add(value: Document?): Boolean =
             content.add(value ?: Document.Null)
+        fun add(@Suppress("UNUSED_PARAMETER") value: Nothing?): Boolean =
+            content.add(Document.Null)
 
         @JvmName("addAllNumbers") fun addAll(value: List<Number?>) = value.forEach(::add)
         @JvmName("addAllStrings") fun addAll(value: List<String?>) = value.forEach(::add)

runtime/runtime-core/common/test/aws/smithy/kotlin/runtime/DocumentBuilderTest.kt

@@ -11,7 +11,7 @@ import kotlin.test.*
 
 class DocumentBuilderTest {
     @Test
-    fun buildsAnObject() {
+    fun itBuildsAnObject() {
         val doc = buildDocument {
             "foo" to 1
             "baz" to buildList {
@@ -30,4 +30,58 @@ class DocumentBuilderTest {
         assertEquals(expected, "$doc")
         assertEquals(1, doc.asMap()["foo"]?.asInt())
     }
+
+    @Test
+    fun itRejectsDoubleInfinity() {
+        assertFailsWith<IllegalArgumentException>(
+            "a document number cannot be Infinity, as its value cannot be preserved across serde"
+        ) {
+            Document(Double.POSITIVE_INFINITY)
+        }
+    }
+
+    @Test
+    fun itRejectsDoubleNegativeInfinity() {
+        assertFailsWith<IllegalArgumentException>(
+            "a document number cannot be -Infinity, as its value cannot be preserved across serde"
+        ) {
+            Document(Double.NEGATIVE_INFINITY)
+        }
+    }
+
+    @Test
+    fun itRejectsDoubleNaN() {
+        assertFailsWith<IllegalArgumentException>(
+            "a document number cannot be NaN, as its value cannot be preserved across serde"
+        ) {
+            Document(Double.NaN)
+        }
+    }
+
+    @Test
+    fun itRejectsFloatInfinity() {
+        assertFailsWith<IllegalArgumentException>(
+            "a document number cannot be Infinity, as its value cannot be preserved across serde"
+        ) {
+            Document(Float.POSITIVE_INFINITY)
+        }
+    }
+
+    @Test
+    fun itRejectsFloatNegativeInfinity() {
+        assertFailsWith<IllegalArgumentException>(
+            "a document number cannot be -Infinity, as its value cannot be preserved across serde"
+        ) {
+            Document(Float.NEGATIVE_INFINITY)
+        }
+    }
+
+    @Test
+    fun itRejectsFloatNaN() {
+        assertFailsWith<IllegalArgumentException>(
+            "a document number cannot be NaN, as its value cannot be preserved across serde"
+        ) {
+            Document(Float.NaN)
+        }
+    }
 }

runtime/serde/common/src/aws/smithy/kotlin/runtime/serde/Deserializer.kt

@@ -4,6 +4,8 @@
  */
 package aws.smithy.kotlin.runtime.serde
 
+import aws.smithy.kotlin.runtime.smithy.Document
+
 /**
  * Deserializer is a format agnostic deserialization interface. Specific formats (e.g. JSON, XML, etc) implement
  * this interface and handle the underlying raw decoding process and deal with details specific to that format.
@@ -190,6 +192,14 @@ interface PrimitiveDeserializer {
      */
     fun deserializeBoolean(): Boolean
 
+    /**
+     * Deserialize and return the next token as a [Document].
+     *
+     * If the document's value is a list or map, this method will deserialize all elements or fields recursively - the
+     * caller need not further inspect the value to attempt to do so manually.
+     */
+    fun deserializeDocument(): Document
+
     /**
      * Consume the next token if represents a null value. Always returns null.
      */

runtime/serde/common/src/aws/smithy/kotlin/runtime/serde/Serializer.kt

@@ -3,6 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0.
  */
 package aws.smithy.kotlin.runtime.serde
+import aws.smithy.kotlin.runtime.smithy.Document
 import aws.smithy.kotlin.runtime.time.Instant
 import aws.smithy.kotlin.runtime.time.TimestampFormat
 
@@ -129,6 +130,15 @@ interface StructSerializer : PrimitiveSerializer {
      */
     fun field(descriptor: SdkFieldDescriptor, value: Instant, format: TimestampFormat)
 
+    /**
+     * Writes the field name given in the descriptor, and then
+     * serializes value.
+     *
+     * @param descriptor
+     * @param value
+     */
+    fun field(descriptor: SdkFieldDescriptor, value: Document)
+
     /**
      * Writes the field name given in the descriptor, and then
      * serializes value.

runtime/serde/serde-form-url/common/src/aws/smithy/kotlin/runtime/serde/formurl/FormUrlSerializer.kt

@@ -9,6 +9,7 @@ import aws.smithy.kotlin.runtime.io.SdkByteBuffer
 import aws.smithy.kotlin.runtime.io.bytes
 import aws.smithy.kotlin.runtime.io.write
 import aws.smithy.kotlin.runtime.serde.*
+import aws.smithy.kotlin.runtime.smithy.Document
 import aws.smithy.kotlin.runtime.time.Instant
 import aws.smithy.kotlin.runtime.time.TimestampFormat
 import aws.smithy.kotlin.runtime.util.text.urlEncodeComponent
@@ -130,6 +131,12 @@ private class FormUrlStructSerializer(
         serializeInstant(value, format)
     }
 
+    override fun field(descriptor: SdkFieldDescriptor, value: Document) {
+        throw SerializationException(
+            "cannot serialize field ${descriptor.serialName}; Document type is not supported by form-url encoding"
+        )
+    }
+
     override fun field(descriptor: SdkFieldDescriptor, value: SdkSerializable) {
         val nestedPrefix = "${prefix}${descriptor.serialName}."
         // prepend the current prefix if one exists (e.g. deeply nested structures)

runtime/serde/serde-json/common/src/aws/smithy/kotlin/runtime/serde/json/JsonDeserializer.kt

@@ -5,6 +5,7 @@
 package aws.smithy.kotlin.runtime.serde.json
 
 import aws.smithy.kotlin.runtime.serde.*
+import aws.smithy.kotlin.runtime.smithy.Document
 
 /**
  * Provides a deserializer for JSON documents
@@ -33,6 +34,10 @@ class JsonDeserializer(payload: ByteArray) : Deserializer, Deserializer.ElementI
 
     override fun deserializeDouble(): Double = nextNumberValue { it.toDouble() }
 
+    // deserializes the next token as a number with the maximum discernible precision
+    private fun deserializeNumber(): Number =
+        nextNumberValue { if (it.contains('.')) it.toDouble() else it.toLong() }
+
     // assert the next token is a Number and execute [block] with the raw value as a string. Returns result
     // of executing the block. This is mostly so that numeric conversions can keep as much precision as possible
     private fun <T> nextNumberValue(block: (value: String) -> T): T {
@@ -58,6 +63,41 @@ class JsonDeserializer(payload: ByteArray) : Deserializer, Deserializer.ElementI
         return token.value
     }
 
+    override fun deserializeDocument(): Document =
+        when (val token = reader.peek()) {
+            is JsonToken.Number -> Document(deserializeNumber())
+            is JsonToken.String -> Document(deserializeString())
+            is JsonToken.Bool -> Document(deserializeBoolean())
+            JsonToken.Null -> {
+                reader.nextToken()
+                Document.Null
+            }
+            JsonToken.BeginArray ->
+                deserializeList(SdkFieldDescriptor(SerialKind.Document)) {
+                    val values = mutableListOf<Document>()
+                    while (hasNextElement()) {
+                        values.add(deserializeDocument())
+                    }
+                    Document.List(values)
+                }
+            JsonToken.BeginObject ->
+                deserializeMap(SdkFieldDescriptor(SerialKind.Document)) {
+                    val values = mutableMapOf<String, Document>()
+                    while (hasNextEntry()) {
+                        values[key()] = deserializeDocument()
+                    }
+                    Document.Map(values)
+                }
+            JsonToken.EndArray, JsonToken.EndObject, JsonToken.EndDocument ->
+                throw DeserializationException(
+                    "encountered unexpected json token \"$token\" while deserializing document"
+                )
+            is JsonToken.Name ->
+                throw DeserializationException(
+                    "encountered unexpected json field declaration \"${token.value}\" while deserializing document"
+                )
+        }
+
     override fun deserializeNull(): Nothing? {
         reader.nextTokenOf<JsonToken.Null>()
         return null

runtime/serde/serde-json/common/src/aws/smithy/kotlin/runtime/serde/json/JsonEncoder.kt

@@ -108,6 +108,7 @@ internal class JsonEncoder(private val pretty: Boolean = false) : JsonStreamWrit
 
     private fun writeNumber(value: Number) = encodeValue(value.toString())
 
+    override fun writeValue(value: Number) = writeNumber(value)
     override fun writeValue(value: Byte) = writeNumber(value)
     override fun writeValue(value: Long) = writeNumber(value)
     override fun writeValue(value: Short) = writeNumber(value)

runtime/serde/serde-json/common/src/aws/smithy/kotlin/runtime/serde/json/JsonSerializer.kt

@@ -5,6 +5,7 @@
 package aws.smithy.kotlin.runtime.serde.json
 
 import aws.smithy.kotlin.runtime.serde.*
+import aws.smithy.kotlin.runtime.smithy.Document
 import aws.smithy.kotlin.runtime.time.Instant
 import aws.smithy.kotlin.runtime.time.TimestampFormat
 
@@ -101,6 +102,11 @@ class JsonSerializer : Serializer, ListSerializer, MapSerializer, StructSerializ
         serializeInstant(value, format)
     }
 
+    override fun field(descriptor: SdkFieldDescriptor, value: Document) {
+        jsonWriter.writeName(descriptor.serialName)
+        serializeDocument(value)
+    }
+
     override fun nullField(descriptor: SdkFieldDescriptor) {
         jsonWriter.writeName(descriptor.serialName)
         serializeNull()
@@ -252,4 +258,26 @@ class JsonSerializer : Serializer, ListSerializer, MapSerializer, StructSerializ
             -> jsonWriter.writeValue(value.format(format))
         }
     }
+
+    fun serializeDocument(value: Document) {
+        when (value) {
+            is Document.Number -> jsonWriter.writeValue(value.value)
+            is Document.String -> jsonWriter.writeValue(value.value)
+            is Document.Boolean -> jsonWriter.writeValue(value.value)
+            is Document.Null -> jsonWriter.writeNull()
+            is Document.List -> {
+                jsonWriter.beginArray()
+                value.value.forEach(::serializeDocument)
+                jsonWriter.endArray()
+            }
+            is Document.Map -> {
+                jsonWriter.beginObject()
+                value.value.entries.forEach {
+                    jsonWriter.writeName(it.key)
+                    serializeDocument(it.value)
+                }
+                jsonWriter.endObject()
+            }
+        }
+    }
 }

runtime/serde/serde-json/common/src/aws/smithy/kotlin/runtime/serde/json/JsonStreamWriter.kt

@@ -58,6 +58,11 @@ interface JsonStreamWriter {
      */
     fun writeValue(bool: Boolean)
 
+    /**
+     * Encodes {@code value}.
+     */
+    fun writeValue(value: Number)
+
     /**
      * Encodes {@code value}.
      */