RFC30

aws/sdk-codegen/src/main/kotlin/software/amazon/smithy/rustsdk/AwsCrateDocsDecorator.kt

@@ -11,6 +11,7 @@ import org.jsoup.nodes.TextNode
 import software.amazon.smithy.model.traits.DocumentationTrait
 import software.amazon.smithy.rust.codegen.client.smithy.ClientCodegenContext
 import software.amazon.smithy.rust.codegen.client.smithy.customize.ClientCodegenDecorator
+import software.amazon.smithy.rust.codegen.client.smithy.customize.SerdeDecorator
 import software.amazon.smithy.rust.codegen.core.rustlang.CargoDependency
 import software.amazon.smithy.rust.codegen.core.rustlang.RustWriter
 import software.amazon.smithy.rust.codegen.core.rustlang.Writable

buildSrc/src/main/kotlin/CodegenTestCommon.kt

@@ -268,29 +268,25 @@ fun Project.registerCargoCommandsTasks(
     this.tasks.register<Exec>(Cargo.CHECK.toString) {
         dependsOn(dependentTasks)
         workingDir(outputDir)
-        environment("RUSTFLAGS", "--cfg aws_sdk_unstable")
         commandLine("cargo", "check", "--lib", "--tests", "--benches", "--all-features")
     }
 
     this.tasks.register<Exec>(Cargo.TEST.toString) {
         dependsOn(dependentTasks)
         workingDir(outputDir)
-        environment("RUSTFLAGS", "--cfg aws_sdk_unstable")
         commandLine("cargo", "test", "--all-features", "--no-fail-fast")
     }
 
     this.tasks.register<Exec>(Cargo.DOCS.toString) {
         dependsOn(dependentTasks)
         workingDir(outputDir)
         environment("RUSTDOCFLAGS", defaultRustDocFlags)
-        environment("RUSTFLAGS", "--cfg aws_sdk_unstable")
         commandLine("cargo", "doc", "--no-deps", "--document-private-items")
     }
 
     this.tasks.register<Exec>(Cargo.CLIPPY.toString) {
         dependsOn(dependentTasks)
         workingDir(outputDir)
-        environment("RUSTFLAGS", "--cfg aws_sdk_unstable")
         commandLine("cargo", "clippy")
     }
 }

codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/RustClientCodegenPlugin.kt

@@ -18,6 +18,7 @@ import software.amazon.smithy.rust.codegen.client.smithy.customizations.Sensitiv
 import software.amazon.smithy.rust.codegen.client.smithy.customize.ClientCodegenDecorator
 import software.amazon.smithy.rust.codegen.client.smithy.customize.CombinedClientCodegenDecorator
 import software.amazon.smithy.rust.codegen.client.smithy.customize.RequiredCustomizations
+import software.amazon.smithy.rust.codegen.client.smithy.customize.SerdeDecorator
 import software.amazon.smithy.rust.codegen.client.smithy.endpoint.EndpointParamsDecorator
 import software.amazon.smithy.rust.codegen.client.smithy.endpoint.EndpointsDecorator
 import software.amazon.smithy.rust.codegen.client.smithy.generators.client.FluentClientDecorator
@@ -59,6 +60,7 @@ class RustClientCodegenPlugin : ClientDecoratableBuildPlugin() {
         val codegenDecorator =
             CombinedClientCodegenDecorator.fromClasspath(
                 context,
+                SerdeDecorator(),
                 ClientCustomizations(),
                 RequiredCustomizations(),
                 FluentClientDecorator(),

codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/customize/SerdeDecorator.kt

@@ -0,0 +1,83 @@
+/*
+* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+* SPDX-License-Identifier: Apache-2.0
+*/
+
+package software.amazon.smithy.rust.codegen.client.smithy.customize
+
+import software.amazon.smithy.rust.codegen.client.smithy.ClientCodegenContext
+import software.amazon.smithy.rust.codegen.core.rustlang.containerDocs
+import software.amazon.smithy.rust.codegen.core.rustlang.Feature
+import software.amazon.smithy.rust.codegen.core.rustlang.RustWriter
+import software.amazon.smithy.rust.codegen.core.rustlang.Writable
+import software.amazon.smithy.rust.codegen.core.rustlang.writable
+import software.amazon.smithy.rust.codegen.core.smithy.RustCrate
+import software.amazon.smithy.rust.codegen.core.smithy.generators.LibRsCustomization
+import software.amazon.smithy.rust.codegen.core.smithy.generators.LibRsSection
+import software.amazon.smithy.rust.codegen.core.smithy.generators.ModuleDocSection
+
+/**
+ * Decorator that adds the `serde-serialize` and `serde-deserialize` features.
+ */
+class SerdeDecorator : ClientCodegenDecorator {
+    override val name: String = "SerdeDecorator"
+    override val order: Byte = 5
+
+    override fun extras(codegenContext: ClientCodegenContext, rustCrate: RustCrate) {
+        fun feature(featureName: String): Feature {
+            return Feature(featureName, false, listOf("aws-smithy-types/$featureName"))
+        }
+        rustCrate.mergeFeature(feature("serde-serialize"))
+        rustCrate.mergeFeature(feature("serde-deserialize"))
+
+    }
+
+    override fun libRsCustomizations(
+        codegenContext: ClientCodegenContext,
+        baseCustomizations: List<LibRsCustomization>
+    ): List<LibRsCustomization> {
+        return baseCustomizations + SerdeDocGenerator(codegenContext)
+    }
+}
+
+class SerdeDocGenerator(private val codegenContext: ClientCodegenContext) : LibRsCustomization() {
+    override fun section(section: LibRsSection): Writable {
+        return when (section) {
+            is LibRsSection.ModuleDoc->
+                if (section.subsection is ModuleDocSection.AWSSdkUnstable) {
+                    serdeInfoText()
+                } else {
+                    emptySection
+                }
+
+            else -> emptySection
+        }
+    }
+
+    private fun serdeInfoText(): Writable {
+        return writable {
+            containerDocs(
+                """
+                ## How to enable `Serialize` and `Deserialize`
+
+                This data type implements `Serialize` and `Deserialize` traits from the popular serde crate, but those traits are behind feature gate.
+
+                As they increase it's compile time dramatically, you should not turn them on unless it's necessary.
+                Implementation of `serde` traits in AWS SDK for Rust is still unstable, and implementation may change anytime in future.
+
+                To enable traits, you must pass `aws_sdk_unstable` to RUSTFLAGS and enable `serde-serialize` or `serde-deserialize` feature.
+
+                e.g.
+                ```bash,no_run
+                export RUSTFLAGS="--cfg aws_sdk_unstable"
+                cargo build --features serde-serialize serde-deserialize
+                ```
+
+                If you enable `serde-serialize` and/or `serde-deserialize` without `RUSTFLAGS="--cfg aws_sdk_unstable"`,
+                compilation will fail with warning.
+
+                """.trimIndent()
+            )
+        }
+    }
+}

codegen-client/src/main/kotlin/software/amazon/smithy/rust/codegen/client/smithy/generators/ClientEnumGenerator.kt

@@ -23,6 +23,7 @@ import software.amazon.smithy.rust.codegen.core.smithy.generators.EnumGenerator
 import software.amazon.smithy.rust.codegen.core.smithy.generators.EnumGeneratorContext
 import software.amazon.smithy.rust.codegen.core.smithy.generators.EnumMemberModel
 import software.amazon.smithy.rust.codegen.core.smithy.generators.EnumType
+import software.amazon.smithy.rust.codegen.core.smithy.generators.RenderSerdeAttribute
 import software.amazon.smithy.rust.codegen.core.util.dq
 
 /** Infallible enums have an `Unknown` variant and can't fail to parse */
@@ -158,6 +159,8 @@ data class InfallibleEnumType(
                 This is not intended to be used directly.
                 """.trimIndent(),
             )
+
+            RenderSerdeAttribute.addSerdeWithoutShapeModel(this)
             context.enumMeta.render(this)
             rustTemplate("struct $UnknownVariantValue(pub(crate) #{String});", *preludeScope)
             rustBlock("impl $UnknownVariantValue") {

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/rustlang/RustType.kt

@@ -667,6 +667,11 @@ class Attribute(val inner: Writable, val isDeriveHelper: Boolean = false) {
                 }
             }
 
+        fun attributeWithStringAsArgument(runtimeType: RuntimeType, comment: String): Writable = {
+            // Sorted derives look nicer than unsorted, and it makes test output easier to predict
+            rustInline("#W(\"$comment\")", runtimeType.writable)
+        }
+
         fun derive(runtimeTypes: Collection<RuntimeType>): Writable = derive(*runtimeTypes.toTypedArray())
 
         fun pair(pair: Pair<String, String>): Writable =

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/BuilderGenerator.kt

@@ -308,11 +308,16 @@ class BuilderGenerator(
         writer.docs("A builder for #D.", structureSymbol)
         metadata.additionalAttributes.render(writer)
         Attribute(derive(builderDerives)).render(writer)
+        RenderSerdeAttribute.addSerde(writer, shape, model)
+        RenderSerdeAttribute.addSensitiveWarningDoc(writer, shape, model)
         writer.rustBlock("pub struct $builderName") {
+            // add serde
             for (member in members) {
                 val memberName = symbolProvider.toMemberName(member)
                 // All fields in the builder are optional.
                 val memberSymbol = symbolProvider.toSymbol(member).makeOptional()
+                RenderSerdeAttribute.skipIfStream(writer, member, model, shape)
+                RenderSerdeAttribute.addSensitiveWarningDoc(writer, shape, model)
                 renderBuilderMember(this, memberName, memberSymbol)
             }
             writeCustomizations(customizations, BuilderSection.AdditionalFields(shape))

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/CargoTomlGenerator.kt

@@ -110,9 +110,18 @@ class CargoTomlGenerator(
                 "dev-dependencies" to
                     dependencies.filter { it.scope == DependencyScope.Dev }
                         .associate { it.name to it.toMap() },
+                "target.'cfg(aws_sdk_unstable)'.dependencies" to dependencies.filter {
+                    it.scope == DependencyScope.CfgUnstable
+                }
+                .associate { it.name to it.toMap() },
                 "features" to cargoFeatures.toMap(),
             ).deepMergeWith(manifestCustomizations)
 
-        writer.writeWithNoFormatting(TomlWriter().write(cargoToml))
+        // NOTE: without this it will produce ["target.'cfg(aws_sdk_unstable)'.dependencies"]
+        // In JSON, this is an equivalent of: {"target.'cfg(aws_sdk_unstable)'.dependencies" : ...}
+        // To make it work, it has to be: {"target": {'cfg(aws_sdk_unstable)': {"dependencies": ...}}}
+        // This piece of code fixes it.
+        var tomlString = TomlWriter().write(cargoToml).replace("\"target.'cfg(aws_sdk_unstable)'.dependencies\"", "target.'cfg(aws_sdk_unstable)'.dependencies")
+        writer.writeWithNoFormatting(tomlString)
     }
 }

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/EnumGenerator.kt

@@ -229,6 +229,8 @@ open class EnumGenerator(
     private fun RustWriter.renderUnnamedEnum() {
         documentShape(shape, model)
         deprecatedShape(shape)
+        RenderSerdeAttribute.addSerde(this, shape, model)
+        RenderSerdeAttribute.addSensitiveWarningDoc(this, shape, model)
         context.enumMeta.render(this)
         rust("struct ${context.enumName}(String);")
         implBlock(
@@ -279,6 +281,8 @@ open class EnumGenerator(
         )
         deprecatedShape(shape)
 
+        RenderSerdeAttribute.addSerde(this, shape, model)
+        RenderSerdeAttribute.addSensitiveWarningDoc(this, shape, model)
         context.enumMeta.render(this)
         rustBlock("enum ${context.enumName}") {
             context.sortedMembers.forEach { member -> member.render(this) }

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/LibRsGenerator.kt

@@ -25,6 +25,8 @@ sealed class ModuleDocSection {
     object CrateOrganization : ModuleDocSection()
 
     object Examples : ModuleDocSection()
+
+    object AWSSdkUnstable : ModuleDocSection()
 }
 
 sealed class LibRsSection(name: String) : Section(name) {
@@ -78,6 +80,16 @@ class LibRsGenerator(
                 }
             }
 
+            docSection(ModuleDocSection.AWSSdkUnstable).also { docs ->
+                if (docs.isNotEmpty()) {
+                    containerDocs("\n## Enabling Unstable Features")
+                    docs.forEach { writeTo ->
+                        writeTo(this)
+                    }
+                }
+            }
+
+
             // Examples
             docSection(ModuleDocSection.Examples).also { docs ->
                 if (docs.isNotEmpty() || settings.examplesUri != null) {

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/RenderSerdeAttribute.kt

@@ -0,0 +1,62 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.rust.codegen.core.smithy.generators
+
+import software.amazon.smithy.model.Model
+import software.amazon.smithy.model.shapes.MemberShape
+import software.amazon.smithy.model.shapes.Shape
+import software.amazon.smithy.model.traits.ErrorTrait
+import software.amazon.smithy.model.traits.SensitiveTrait
+import software.amazon.smithy.rust.codegen.core.rustlang.Attribute
+import software.amazon.smithy.rust.codegen.core.rustlang.RustWriter
+import software.amazon.smithy.rust.codegen.core.rustlang.raw
+import software.amazon.smithy.rust.codegen.core.util.hasTrait
+import software.amazon.smithy.rust.codegen.core.util.isEventStream
+import software.amazon.smithy.rust.codegen.core.util.isStreaming
+
+// Part of RFC30
+public object RenderSerdeAttribute {
+    private const val warningMessage = "/// This data may contain sensitive information; It will not be obscured when serialized.\n"
+    private const val skipFieldMessage = "/// This field will note be serialized or deserialized because it's a stream type.\n"
+
+    // guards to check if you want to add serde attributes
+    fun isApplicable(shape: Shape, model: Model): Boolean {
+        return !shape.hasTrait<ErrorTrait>() && shape.members().none { it.isEventStream(model) }
+    }
+
+    public fun addSensitiveWarningDoc(writer: RustWriter, shape: Shape, model: Model) {
+        if (isApplicable(shape, model) && shape.hasTrait<SensitiveTrait>()) {
+            writer.writeInline(warningMessage)
+        }
+    }
+
+    public fun addSerdeWithoutShapeModel(writer: RustWriter) {
+        Attribute("").SerdeSerialize().render(writer)
+        Attribute("").SerdeDeserialize().render(writer)
+    }
+
+    public fun addSerde(writer: RustWriter, shape: Shape, model: Model) {
+        if (isApplicable(shape, model)) {
+            addSerdeWithoutShapeModel(writer)
+        }
+    }
+
+    public fun skipIfStream(writer: RustWriter, member: MemberShape, model: Model, shape: Shape) {
+        if (isApplicable(shape, model) && member.isStreaming(model)) {
+            writer.writeInline(skipFieldMessage)
+            Attribute("").serdeSkip().render(writer)
+        }
+    }
+
+    public fun importSerde(writer: RustWriter, shape: Shape, model: Model) {
+        if (isApplicable(shape, model)) {
+            // we need this for skip serde to work
+            Attribute.AllowUnusedImports.render(writer)
+            Attribute("").SerdeSerializeOrDeserialize().render(writer)
+            writer.raw("use serde;")
+        }
+    }
+}

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/StructureGenerator.kt

@@ -173,7 +173,9 @@ open class StructureGenerator(
         memberName: String,
         memberSymbol: Symbol,
     ) {
+        RenderSerdeAttribute.skipIfStream(writer, member, model, shape)
         writer.renderMemberDoc(member, memberSymbol)
+        RenderSerdeAttribute.addSensitiveWarningDoc(writer, shape, model)
         writer.deprecatedShape(member)
         memberSymbol.expectRustMetadata().render(writer)
         writer.write("$memberName: #T,", memberSymbol)
@@ -184,6 +186,8 @@ open class StructureGenerator(
         val containerMeta = symbol.expectRustMetadata()
         writer.documentShape(shape, model)
         writer.deprecatedShape(shape)
+        RenderSerdeAttribute.addSerde(writer, shape, model)
+        RenderSerdeAttribute.addSensitiveWarningDoc(writer, shape, model)
         containerMeta.render(writer)
 
         writer.rustBlock("struct $name ${shape.lifetimeDeclaration(symbolProvider)}") {
@@ -193,6 +197,7 @@ open class StructureGenerator(
             writeCustomizations(customizations, StructureSection.AdditionalFields(shape))
         }
 
+        RenderSerdeAttribute.importSerde(writer, shape, model)
         renderStructureImpl()
         if (!containerMeta.hasDebugDerive()) {
             renderDebugImpl()

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/UnionGenerator.kt

@@ -66,7 +66,7 @@ open class UnionGenerator(
     open fun render() {
         writer.documentShape(shape, model)
         writer.deprecatedShape(shape)
-
+        RenderSerdeAttribute.addSerde(writer, shape, model)
         val containerMeta = unionSymbol.expectRustMetadata()
         containerMeta.render(writer)