add comments

Author: luigi

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/service/ServiceStubConfigurations.kt

@@ -12,6 +12,16 @@ import software.amazon.smithy.model.traits.HttpPayloadTrait
 import software.amazon.smithy.model.traits.MediaTypeTrait
 import software.amazon.smithy.protocol.traits.Rpcv2CborTrait
 
+/**
+ * Enumeration of supported media types used by the generated service.
+ *
+ * These values define how payloads are encoded/decoded:
+ * - `CBOR`         → Concise Binary Object Representation
+ * - `JSON`         → JSON encoding
+ * - `PLAIN_TEXT`   → Text/plain
+ * - `OCTET_STREAM` → Binary data
+ * - `ANY`          → Fallback for arbitrary content types
+ */
 enum class MediaType(val value: String) {
     CBOR("CBOR"),
     JSON("JSON"),
@@ -57,6 +67,12 @@ enum class MediaType(val value: String) {
     }
 }
 
+/**
+ * Enumeration of supported service frameworks for generated stubs.
+ *
+ * Currently only supports:
+ * - `KTOR`: Generates Ktor-based service stubs
+ */
 enum class ServiceFramework(val value: String) {
     KTOR("ktor"),
     ;

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/service/ServiceStubGenerator.kt

@@ -10,10 +10,29 @@ import software.amazon.smithy.kotlin.codegen.core.withBlock
 import software.amazon.smithy.kotlin.codegen.core.withInlineBlock
 import software.amazon.smithy.model.knowledge.TopDownIndex
 
+/**
+ * Interface representing a generator that produces service stubs (boilerplate code) for a Smithy service.
+ */
 internal interface ServiceStubGenerator {
+    /**
+     * Render the stub code into the target files.
+     */
     fun render()
 }
 
+/**
+ * Abstract base class for generating service stubs.
+ *
+ * Provides a framework for generating common service artifacts such as:
+ * - Configuration (`ServiceFrameworkConfig.kt`)
+ * - Framework bootstrap (`ServiceFramework.kt`)
+ * - Plugins, utils, authentication, validators
+ * - Operation handlers and routing
+ * - Main launcher (`Main.kt`)
+ *
+ * Concrete subclasses must implement abstract methods for framework-specific
+ * code (e.g., Ktor).
+ */
 internal abstract class AbstractStubGenerator(
     val ctx: GenerationContext,
     val delegator: KotlinDelegator,
@@ -27,6 +46,10 @@ internal abstract class AbstractStubGenerator(
 
     val pkgName = ctx.settings.pkg.name
 
+    /**
+     * Render all service stub files by invoking the component renderers.
+     * This acts as the main entrypoint for code generation.
+     */
     final override fun render() {
         renderServiceFrameworkConfig()
         renderServiceFramework()
@@ -39,7 +62,16 @@ internal abstract class AbstractStubGenerator(
         renderMainFile()
     }
 
-    /** Emits the `ServiceFrameworkConfig.kt` file. */
+    /**
+     * Generate the service configuration file (`ServiceFrameworkConfig.kt`).
+     *
+     * Defines enums for:
+     * - `LogLevel`: Logging verbosity levels
+     * - `ServiceEngine`: Available server engines (Netty, CIO, Jetty)
+     *
+     * Provides a singleton `ServiceFrameworkConfig` object that stores runtime
+     * settings such as port, engine, region, timeouts, and log level.
+     */
     protected fun renderServiceFrameworkConfig() {
         delegator.useFileWriter("ServiceFrameworkConfig.kt", "${ctx.settings.pkg.name}.config") { writer ->
             writer.withBlock("internal enum class LogLevel(val value: String) {", "}") {
@@ -143,7 +175,12 @@ internal abstract class AbstractStubGenerator(
         }
     }
 
-    /** Emits ServiceFramework.kt and other engine bootstrap code. */
+    /**
+     * Generate the service framework interface and bootstrap (`ServiceFramework.kt`).
+     *
+     * Declares a common `ServiceFramework` interface with lifecycle methods and
+     * delegates framework-specific implementation details to subclasses.
+     */
     protected fun renderServiceFramework() {
         delegator.useFileWriter("ServiceFramework.kt", "${ctx.settings.pkg.name}.framework") { writer ->
 
@@ -157,27 +194,36 @@ internal abstract class AbstractStubGenerator(
         }
     }
 
+    /** Render the specific server framework implementation (e.g., Ktor). */
     protected abstract fun renderServerFrameworkImplementation(writer: KotlinWriter)
 
-    /** Emits content-type guards, error handler plugins, … */
+    /** Generate service plugins such as content-type guards, error handlers, etc. */
     protected abstract fun renderPlugins()
 
-    /** Emits utils. */
+    /** Generate supporting utility classes and functions. */
     protected abstract fun renderUtils()
 
-    /** Auth interfaces & installers (bearer, IAM, …). */
+    /** Generate authentication module interfaces and installers (e.g., bearer auth, SigV4, SigV4A). */
     protected abstract fun renderAuthModule()
 
-    /** Request-level Smithy constraint validators. */
+    /** Generate request-level constraint validators for Smithy model constraints. */
     protected abstract fun renderConstraintValidators()
 
-    /** One handler file per Smithy operation. */
+    /** Generate a request handler for each Smithy operation. */
     protected abstract fun renderPerOperationHandlers()
 
-    /** Route table that maps operations → runtime endpoints. */
+    /** Generate the route table that maps Smithy operations to runtime endpoints. */
     protected abstract fun renderRouting()
 
-    /** Writes the top-level `Main.kt` launcher. */
+    /**
+     * Generate the top-level `Main.kt` launcher file.
+     *
+     * This file provides the `main()` entrypoint:
+     * - Parses command-line arguments
+     * - Applies defaults for configuration values
+     * - Initializes the `ServiceFrameworkConfig`
+     * - Starts the appropriate service framework
+     */
     protected fun renderMainFile() {
         val portName = "port"
         val engineFactoryName = "engineFactory"

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/service/constraints/ConstraintGenerator.kt

@@ -10,6 +10,16 @@ import software.amazon.smithy.model.shapes.StructureShape
 import software.amazon.smithy.model.traits.RequiredTrait
 import kotlin.collections.iterator
 
+/**
+ * Generates validation code for request constraints on Smithy operation inputs.
+ *
+ * For a given [operation], this generator traverses the input structure and:
+ * - Recursively inspects members of structures and lists.
+ * - Applies trait-based validations (e.g., required, length, range).
+ * - Emits Kotlin validation functions that check constraints at runtime.
+ *
+ * Output is written into a `<Operation>RequestConstraints.kt` file in the generated `constraints` package.
+ */
 internal class ConstraintGenerator(
     val ctx: GenerationContext,
     val operation: OperationShape,
@@ -21,9 +31,23 @@ internal class ConstraintGenerator(
     val opName = operation.id.name
     val pkgName = ctx.settings.pkg.name
 
+    /**
+     * Entry point for emitting validation code for the operation’s request type.
+     * Delegates to [renderRequestConstraintsValidation].
+     */
     fun render() {
         renderRequestConstraintsValidation()
     }
+
+    /**
+     * Recursively generates validation code for a given [memberShape].
+     *
+     * - If the target is a list, iterates over elements and validates them.
+     * - If the target is a structure, recursively validates its members.
+     * - For each trait (on the member or its target), invokes the matching trait generator.
+     *   - `@required` traits are always enforced.
+     *   - Other traits are wrapped in a null check before validation.
+     */
     private fun generateConstraintValidations(prefix: String, memberShape: MemberShape, writer: KotlinWriter) {
         val targetShape = ctx.model.expectShape(memberShape.target)
 
@@ -59,6 +83,12 @@ internal class ConstraintGenerator(
         }
     }
 
+    /**
+     * Writes the top-level validation function for the operation’s input type.
+     *
+     * Inside, it calls [generateConstraintValidations] for each input member,
+     * ensuring all modeled constraints are enforced.
+     */
     private fun renderRequestConstraintsValidation() {
         delegator.useFileWriter("${opName}RequestConstraints.kt", "$pkgName.constraints") { writer ->
             val inputShape = ctx.model.expectShape(operation.input.get())

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/service/constraints/ConstraintUtilsGenerator.kt

@@ -5,6 +5,15 @@ import software.amazon.smithy.kotlin.codegen.core.KotlinDelegator
 import software.amazon.smithy.kotlin.codegen.core.KotlinWriter
 import software.amazon.smithy.kotlin.codegen.core.withBlock
 
+/**
+ * Generates utility functions to support constraint validation for Smithy models.
+ *
+ * This generator emits reusable helpers that can be called from operation-specific
+ * validation code (e.g., generated by [ConstraintGenerator]). These helpers enforce
+ * common traits like `@length` and `@uniqueItems`.
+ *
+ * Output is written into a `utils.kt` file under the generated `constraints` package.
+ */
 internal class ConstraintUtilsGenerator(
     val ctx: GenerationContext,
     val delegator: KotlinDelegator,
@@ -20,6 +29,16 @@ internal class ConstraintUtilsGenerator(
         }
     }
 
+    /**
+     * Emits the `sizeOf()` function.
+     *
+     * This utility computes a generalized "size" for multiple types:
+     * - Collections, arrays, maps → `size`
+     * - Strings → Unicode code point count
+     * - Byte arrays → length
+     *
+     * Any unsupported type will throw an `IllegalArgumentException`.
+     */
     private fun renderLengthTraitUtils(writer: KotlinWriter) {
         writer.withBlock("internal fun sizeOf(value: Any?): Long = when (value) {", "}") {
             write("is Collection<*> -> value.size.toLong()")
@@ -34,6 +53,16 @@ internal class ConstraintUtilsGenerator(
         }
     }
 
+    /**
+     * Emits the `hasAllUniqueElements()` function.
+     *
+     * This utility checks if a list contains only unique elements, where uniqueness
+     * is defined by deep structural equality:
+     * - Primitive wrappers (String, Boolean, Number, Instant) → compared by value
+     * - Byte arrays → compared by contents
+     * - Lists → recursively compared element by element
+     * - Maps → recursively compared entries by key/value
+     */
     private fun renderUniqueItemsTraitUtils(writer: KotlinWriter) {
         writer.withBlock("internal fun hasAllUniqueElements(elements: List<Any?>): Boolean {", "}") {
             withBlock("class Wrapped(private val v: Any?) {", "}") {

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/service/ktor/Authentication.kt

@@ -7,6 +7,15 @@ import software.amazon.smithy.kotlin.codegen.core.withBlock
 import software.amazon.smithy.kotlin.codegen.model.getTrait
 import software.amazon.smithy.kotlin.codegen.service.ServiceTypes
 
+/**
+ * Writes Ktor-based authentication support classes and configuration
+ * for a generated service.
+ *
+ * This generates three files:
+ * 1. UserPrincipal.kt → Represents the authenticated user.
+ * 2. Validation.kt → Provides bearer token validation logic.
+ * 3. Authentication.kt → Configures authentication providers in Ktor.
+ */
 internal fun KtorStubGenerator.writeAuthentication() {
     delegator.useFileWriter("UserPrincipal.kt", "$pkgName.auth") { writer ->
         writer.withBlock("public data class UserPrincipal(", ")") {

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/service/ktor/AuthenticationAWS.kt

@@ -7,6 +7,14 @@ import software.amazon.smithy.kotlin.codegen.core.withBlock
 import software.amazon.smithy.kotlin.codegen.core.withInlineBlock
 import software.amazon.smithy.kotlin.codegen.lang.KotlinTypes
 
+/**
+ * Writes AWS-specific authentication support for Ktor service stubs.
+ *
+ * This generates the following files:
+ * - AWSValidation.kt → Stub stores for SigV4 credentials and SigV4A public keys.
+ * - AWSSigV4.kt → Ktor authentication provider and verifier for AWS Signature V4 (HMAC).
+ * - AWSSigV4A.kt → Ktor authentication provider and verifier for AWS Signature V4A (ECDSA).
+ */
 internal fun KtorStubGenerator.writeAWSAuthentication() {
     delegator.useFileWriter("AWSValidation.kt", "$pkgName.auth") { writer ->
         writer.withBlock("internal object SigV4CredentialStore {", "}") {
@@ -213,6 +221,10 @@ internal fun KtorStubGenerator.writeAWSAuthentication() {
     }
 }
 
+/**
+ * Extracts and parses AWS authentication header information
+ * (Credential, SignedHeaders, Signature) from a request.
+ */
 private fun retrieveAuthInformation(writer: KotlinWriter, algorithm: String) {
     writer.write("val authHeader = call.request.#T(#T.Authorization) ?: return null", RuntimeTypes.KtorServerRouting.requestHeader, RuntimeTypes.KtorServerHttp.HttpHeaders)
         .write("if (!authHeader.startsWith(#S, ignoreCase = true)) return null", algorithm)
@@ -229,6 +241,9 @@ private fun retrieveAuthInformation(writer: KotlinWriter, algorithm: String) {
         .write("val accessKeyId = credential.substringBefore(#S).takeIf { it.matches(Regex(#S)) } ?: return null", "/", "^[A-Z0-9]{16,128}$")
 }
 
+/**
+ * Validates signing date against request scope date and clock skew.
+ */
 private fun authDateValidation(writer: KotlinWriter) {
     writer.write("val rawXAmzDate = call.request.#T(#S)", RuntimeTypes.KtorServerRouting.requestHeader, "X-Amz-Date")
         .write("val rawHttpDate = call.request.#T(#T.Date)", RuntimeTypes.KtorServerRouting.requestHeader, RuntimeTypes.KtorServerHttp.HttpHeaders)
@@ -244,6 +259,10 @@ private fun authDateValidation(writer: KotlinWriter) {
         .write("if (signingInstant < now - maxClockSkew || signingInstant > now + maxClockSkew) return null")
 }
 
+/**
+ * Builds a full HttpRequestBuilder object from the Ktor request,
+ * used for SigV4 canonical request signing.
+ */
 private fun createHttpRequestBuilder(writer: KotlinWriter) {
     writer.write("val origin = call.request.local")
         .write("val payload: ByteArray = call.#T<ByteArray>()", RuntimeTypes.KtorServerRouting.requestReceive)
@@ -287,6 +306,9 @@ private fun createHttpRequestBuilder(writer: KotlinWriter) {
         }
 }
 
+/**
+ * Builds a canonical request string for SigV4A verification.
+ */
 private fun createCanonicalRequest(writer: KotlinWriter) {
     writer.write("val origin = call.request.local")
         .write("val payload: ByteArray = call.#T<ByteArray>()", RuntimeTypes.KtorServerRouting.requestReceive)
@@ -353,6 +375,9 @@ private fun createCanonicalRequest(writer: KotlinWriter) {
         }
 }
 
+/**
+ * Performs AWS SigV4 signature validation against expected HMAC.
+ */
 private fun validateSigV4(writer: KotlinWriter) {
     writer.withBlock("val signer = #T(", ")", RuntimeTypes.Auth.HttpAuthAws.AwsHttpSigner) {
         withBlock("#T.Config().apply {", "}", RuntimeTypes.Auth.HttpAuthAws.AwsHttpSigner) {
@@ -389,6 +414,9 @@ private fun validateSigV4(writer: KotlinWriter) {
         .write("val expectedSig = expectedAuth.substringAfter(#S).trim()", "Signature=")
 }
 
+/**
+ * Performs AWS SigV4A signature validation against ECDSA public key.
+ */
 private fun validateSigV4A(writer: KotlinWriter) {
     writer.write("val crHashHex = sha256Hex(canonicalRequest.toByteArray())")
         .withBlock("val stringToSign = buildString {", "}") {
@@ -405,6 +433,10 @@ private fun validateSigV4A(writer: KotlinWriter) {
         .write("val ok = verifier.verify(sigDer)")
 }
 
+/**
+ * Writes common helper functions used by SigV4 and SigV4A verification,
+ * such as hashing, encoding, and canonical path/query building.
+ */
 private fun renderHelperFunctions(writer: KotlinWriter) {
     writer.withBlock("private fun sha256Hex(bytes: ByteArray): String {", "}") {
         write("return java.security.MessageDigest.getInstance(#S).digest(bytes).joinToString(#S) { #S.format(it) }", "SHA-256", "", "%02x")