Document the new service builder

codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/DocHandlerGenerator.kt

@@ -18,39 +18,38 @@ import software.amazon.smithy.rust.codegen.core.smithy.Outputs
 import software.amazon.smithy.rust.codegen.core.smithy.generators.error.errorSymbol
 import software.amazon.smithy.rust.codegen.core.util.inputShape
 import software.amazon.smithy.rust.codegen.core.util.outputShape
-import software.amazon.smithy.rust.codegen.core.util.toSnakeCase
 
 /**
 Generates a stub for use within documentation.
  */
-class DocHandlerGenerator(private val operation: OperationShape, private val commentToken: String = "//", private val codegenContext: CodegenContext) {
+class DocHandlerGenerator(private val operation: OperationShape, private val commentToken: String = "//", private val handlerName: String, codegenContext: CodegenContext) {
     private val model = codegenContext.model
     private val symbolProvider = codegenContext.symbolProvider
-    private val crateName = codegenContext.settings.moduleName.toSnakeCase()
+    private val crateName = codegenContext.moduleUseName()
 
     /**
      * Returns the function signature for an operation handler implementation. Used in the documentation.
      */
-    private fun OperationShape.docSignature(): Writable {
-        val inputSymbol = symbolProvider.toSymbol(inputShape(model))
-        val outputSymbol = symbolProvider.toSymbol(outputShape(model))
-        val errorSymbol = errorSymbol(model, symbolProvider, CodegenTarget.SERVER)
+    fun docSignature(): Writable {
+        val inputSymbol = symbolProvider.toSymbol(operation.inputShape(model))
+        val outputSymbol = symbolProvider.toSymbol(operation.outputShape(model))
+        val errorSymbol = operation.errorSymbol(model, symbolProvider, CodegenTarget.SERVER)
 
-        val outputT = if (errors.isEmpty()) {
+        val outputT = if (operation.errors.isEmpty()) {
             outputSymbol.name
         } else {
             "Result<${outputSymbol.name}, ${errorSymbol.name}>"
         }
 
         return writable {
-            if (!errors.isEmpty()) {
+            if (operation.errors.isNotEmpty()) {
                 rust("$commentToken ## use $crateName::${Errors.namespace}::${errorSymbol.name};")
             }
             rust(
                 """
                 $commentToken ## use $crateName::${Inputs.namespace}::${inputSymbol.name};
                 $commentToken ## use $crateName::${Outputs.namespace}::${outputSymbol.name};
-                $commentToken async fn handler(input: ${inputSymbol.name}) -> $outputT {
+                $commentToken async fn $handlerName(input: ${inputSymbol.name}) -> $outputT {
                 $commentToken     todo!()
                 $commentToken }
                 """.trimIndent(),
@@ -59,6 +58,6 @@ class DocHandlerGenerator(private val operation: OperationShape, private val com
     }
 
     fun render(writer: RustWriter) {
-        operation.docSignature()(writer)
+        docSignature()(writer)
     }
 }

codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerOperationShapeGenerator.kt

@@ -62,7 +62,7 @@ class ServerOperationShapeGenerator(
             "SmithyHttpServer" to
                 ServerCargoDependency.SmithyHttpServer(codegenContext.runtimeConfig).toType(),
             "Tower" to ServerCargoDependency.Tower.toType(),
-            "Handler" to DocHandlerGenerator(operations[0], "//!", codegenContext)::render,
+            "Handler" to DocHandlerGenerator(operations[0], "//!", "handler", codegenContext)::render,
         )
         for (operation in operations) {
             ServerOperationGenerator(codegenContext, operation).render(writer)

codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerServiceGeneratorV2.kt

@@ -17,6 +17,9 @@ import software.amazon.smithy.rust.codegen.core.rustlang.rust
 import software.amazon.smithy.rust.codegen.core.rustlang.rustTemplate
 import software.amazon.smithy.rust.codegen.core.rustlang.writable
 import software.amazon.smithy.rust.codegen.core.smithy.CodegenContext
+import software.amazon.smithy.rust.codegen.core.smithy.Errors
+import software.amazon.smithy.rust.codegen.core.smithy.Inputs
+import software.amazon.smithy.rust.codegen.core.smithy.Outputs
 import software.amazon.smithy.rust.codegen.core.util.toPascalCase
 import software.amazon.smithy.rust.codegen.core.util.toSnakeCase
 import software.amazon.smithy.rust.codegen.server.smithy.ServerCargoDependency
@@ -156,7 +159,7 @@ class ServerServiceGeneratorV2(
                 }
                 """,
                 "Protocol" to protocol.markerStruct(),
-                "Handler" to DocHandlerGenerator(operationShape, "///", codegenContext)::render,
+                "Handler" to DocHandlerGenerator(operationShape, "///", "handler", codegenContext)::render,
                 *codegenScope,
             )
 
@@ -469,8 +472,104 @@ class ServerServiceGeneratorV2(
     }
 
     fun render(writer: RustWriter) {
+        val crateName = codegenContext.moduleUseName()
+        val handlers: Writable = operations
+            .map { operation ->
+                DocHandlerGenerator(operation, "///", builderFieldNames[operation]!!, codegenContext).docSignature()
+            }
+            .reduce { acc, wt ->
+                writable {
+                    rustTemplate("#{acc:W} \n#{wt:W}", "acc" to acc, "wt" to wt)
+                }
+            }
+
         writer.rustTemplate(
             """
+            /// A fast and customizable Rust implementation of the $serviceName Smithy service.
+            ///
+            /// This crate provides all types required to setup the [`$serviceName`] Service.
+            /// The [`$crateName::${Inputs.namespace}`], [`$crateName::${Outputs.namespace}`], and [`$crateName::${Errors.namespace}`] modules provide the types used in each operation.
+            ///
+            /// The primary export is [`$serviceName`]: it is the
+            /// [`$builderName`] is used to set your business logic to implement your [operations],
+            /// customize your [operations]'s behaviors by applying middleware,
+            /// and build your service.
+            ///
+            /// [`$builderName`] contains the [operations] modeled in your Smithy service.
+            /// You must set an implementation for all operations with the correct signature,
+            /// or your service will fail to be constructed at runtime and panic.
+            /// For each of the [operations] modeled in
+            /// your Smithy service, you need to provide an implementation in the
+            /// form of an async function that takes in the
+            /// operation's input as their first parameter, and returns the
+            /// operation's output. If your operation is fallible (i.e. it
+            /// contains the `errors` member in your Smithy model), the function
+            /// implementing the operation has to be fallible (i.e. return a [`Result`]).
+            /// The possible forms for your async functions are:
+            /// ```rust
+            /// async fn handler_fallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Result<Output, Error>;
+            /// async fn handler_infallible(input: Input, extensions: #{SmithyHttpServer}Extension<T>) -> Output;
+            /// ```
+            /// Both can take up to 8 extensions, or none:
+            /// ```rust
+            /// async fn handler_with_no_extensions(input: Input) -> ...;
+            /// async fn handler_with_one_extension(input: Input, ext: #{SmithyHttpServer}Extension<T>) -> ...;
+            /// async fn handler_with_two_extensions(input: Input, ext0: #{SmithyHttpServer}Extension<T>, ext1: #{SmithyHttpServer}Extension<T>) -> ...;
+            /// ...
+            /// ```
+            /// For a full list of the possible extensions, see: [`#{SmithyHttpServer}::request`]. Any `T: Send + Sync + 'static` is also allowed.
+            ///
+            /// To construct [`$serviceName`], you can use:
+            /// * [`$serviceName::builder_without_plugins()`] which returns a [`$builderName`] without any service-wide middleware applied.
+            /// * [`$serviceName::builder_with_plugins(plugins)`] which returns a [`$builderName`] that applies `plugins` to all your operations.
+            ///
+            /// To know more about plugins, see: [`#{SmithyHttpServer}::plugin`].
+            ///
+            /// When you have set all your operations, you can convert [`$serviceName`] into a tower [Service] calling:
+            /// * [`$serviceName::into_make_service`] that converts $serviceName into a type that implements [`tower::make::MakeService`], a _service factory_.
+            /// * [`$serviceName::into_make_service_with_connect_info`] that converts $serviceName into [`tower::make::MakeService`]
+            /// with [`ConnectInfo`](#{SmithyHttpServer}::request::connect_info::ConnectInfo).
+            /// You can write your implementations to be passed in the connection information, populated by the [Hyper server], as an [`#{SmithyHttpServer}Extension`].
+            ///
+            /// You can feed this [Service] to a [Hyper server], and the
+            /// server will instantiate and [`serve`] your service.
+            ///
+            /// Here's a full example to get you started:
+            ///
+            /// ```rust
+            /// use std::net::SocketAddr;
+            /// use $crateName::$serviceName;
+            ///
+            /// ##[tokio::main]
+            /// pub async fn main() {
+            ///    let app = $serviceName::builder_without_plugins()
+            ${builderFieldNames.values.joinToString("\n") { "///        .$it($it)" }}
+            ///        .build()
+            ///        .expect("failed to build an instance of $serviceName");
+            ///
+            ///    let bind: SocketAddr = "127.0.0.1:6969".parse()
+            ///        .expect("unable to parse the server bind address and port");
+            ///
+            ///    let server = hyper::Server::bind(&bind).serve(app.into_make_service());
+            ///    ## let server = async { Ok::<_, ()>(()) };
+            ///
+            ///    // Run your service!
+            ///    if let Err(err) = server.await {
+            ///      eprintln!("server error: {}", err);
+            ///    }
+            /// }
+            ///
+            #{Handlers:W}
+            ///
+            /// ```
+            ///
+            /// [`serve`]: https://docs.rs/hyper/0.14.16/hyper/server/struct.Builder.html##method.serve
+            /// [`tower::make::MakeService`]: https://docs.rs/tower/latest/tower/make/trait.MakeService.html
+            /// [HTTP binding traits]: https://smithy.io/2.0/spec/http-bindings.html
+            /// [operations]: https://smithy.io/2.0/spec/service-types.html##operation
+            /// [Hyper server]: https://docs.rs/hyper/latest/hyper/server/index.html
+            /// [Service]: https://docs.rs/tower-service/latest/tower_service/trait.Service.html
+
             #{Builder:W}
 
             #{MissingOperationsError:W}
@@ -483,6 +582,9 @@ class ServerServiceGeneratorV2(
             "MissingOperationsError" to missingOperationsError(),
             "RequestSpecs" to requestSpecsModule(),
             "Struct" to serviceStruct(),
+            "Handlers" to handlers,
+            "ExampleHandler" to operations.take(1).map { operation -> DocHandlerGenerator(operation, "///", builderFieldNames[operation]!!, codegenContext).docSignature() },
+            *codegenScope,
         )
     }
 }