Skip to content

Commit 299e36b

Browse files
hlbarberdavid-perez
hlbarber
and
david-perez
authored
Respect the ShapeVisitor methods - operation_shape.rs (#2486)
* Move ServerOperationGenerator to ShapeVisitor::operationShape * Switch operation_shape docs to ModuleDocProvider * Update codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/ServerRustModule.kt Co-authored-by: david-perez <d@vidp.dev> --------- Co-authored-by: david-perez <d@vidp.dev>
1 parent d89a90d commit 299e36b

File tree

6 files changed

+84
-101
lines changed

6 files changed

+84
-101
lines changed

‎codegen-server/python/src/main/kotlin/software/amazon/smithy/rust/codegen/server/python/smithy/PythonServerCodegenVisitor.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ class PythonServerCodegenVisitor(
119119
codegenContext = codegenContext.copy(
120120
moduleDocProvider = codegenDecorator.moduleDocumentationCustomization(
121121
codegenContext,
122-
PythonServerModuleDocProvider(ServerModuleDocProvider()),
122+
PythonServerModuleDocProvider(ServerModuleDocProvider(codegenContext)),
123123
),
124124
)
125125

‎codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/ServerCodegenVisitor.kt

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ import software.amazon.smithy.rust.codegen.server.smithy.generators.ServerBuilde
6767
import software.amazon.smithy.rust.codegen.server.smithy.generators.ServerBuilderGeneratorWithoutPublicConstrainedTypes
6868
import software.amazon.smithy.rust.codegen.server.smithy.generators.ServerEnumGenerator
6969
import software.amazon.smithy.rust.codegen.server.smithy.generators.ServerOperationErrorGenerator
70+
import software.amazon.smithy.rust.codegen.server.smithy.generators.ServerOperationGenerator
7071
import software.amazon.smithy.rust.codegen.server.smithy.generators.ServerServiceGenerator
7172
import software.amazon.smithy.rust.codegen.server.smithy.generators.ServerStructureConstrainedTraitImpl
7273
import software.amazon.smithy.rust.codegen.server.smithy.generators.UnconstrainedCollectionGenerator
@@ -155,7 +156,7 @@ open class ServerCodegenVisitor(
155156
codegenContext = codegenContext.copy(
156157
moduleDocProvider = codegenDecorator.moduleDocumentationCustomization(
157158
codegenContext,
158-
ServerModuleDocProvider(),
159+
ServerModuleDocProvider(codegenContext),
159160
),
160161
)
161162

@@ -574,12 +575,18 @@ open class ServerCodegenVisitor(
574575
}
575576

576577
/**
577-
* Generate errors for operation shapes
578+
* For each operation shape generate:
579+
* - Errors via `ServerOperationErrorGenerator`
580+
* - OperationShapes via `ServerOperationGenerator`
578581
*/
579582
override fun operationShape(shape: OperationShape) {
580583
rustCrate.withModule(ServerRustModule.Error) {
581584
ServerOperationErrorGenerator(model, codegenContext.symbolProvider, shape).render(this)
582585
}
586+
587+
rustCrate.withModule(ServerRustModule.OperationShape) {
588+
ServerOperationGenerator(shape, codegenContext).render(this)
589+
}
583590
}
584591

585592
override fun blobShape(shape: BlobShape) {

‎codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/ServerRustModule.kt

Lines changed: 73 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
package software.amazon.smithy.rust.codegen.server.smithy
77

88
import software.amazon.smithy.codegen.core.Symbol
9+
import software.amazon.smithy.model.knowledge.TopDownIndex
910
import software.amazon.smithy.model.shapes.OperationShape
1011
import software.amazon.smithy.model.shapes.Shape
1112
import software.amazon.smithy.model.shapes.StructureShape
@@ -16,6 +17,8 @@ import software.amazon.smithy.rust.codegen.core.rustlang.RustReservedWords
1617
import software.amazon.smithy.rust.codegen.core.rustlang.Visibility
1718
import software.amazon.smithy.rust.codegen.core.rustlang.Writable
1819
import software.amazon.smithy.rust.codegen.core.rustlang.docs
20+
import software.amazon.smithy.rust.codegen.core.rustlang.escape
21+
import software.amazon.smithy.rust.codegen.core.rustlang.rustTemplate
1922
import software.amazon.smithy.rust.codegen.core.rustlang.writable
2023
import software.amazon.smithy.rust.codegen.core.smithy.ModuleDocProvider
2124
import software.amazon.smithy.rust.codegen.core.smithy.ModuleProvider
@@ -24,8 +27,10 @@ import software.amazon.smithy.rust.codegen.core.smithy.module
2427
import software.amazon.smithy.rust.codegen.core.smithy.traits.SyntheticInputTrait
2528
import software.amazon.smithy.rust.codegen.core.smithy.traits.SyntheticOutputTrait
2629
import software.amazon.smithy.rust.codegen.core.util.hasTrait
30+
import software.amazon.smithy.rust.codegen.core.util.toPascalCase
2731
import software.amazon.smithy.rust.codegen.core.util.toSnakeCase
28-
32+
import software.amazon.smithy.rust.codegen.server.smithy.generators.DocHandlerGenerator
33+
import software.amazon.smithy.rust.codegen.server.smithy.generators.handlerImports
2934
object ServerRustModule {
3035
val root = RustModule.LibRs
3136

@@ -44,23 +49,73 @@ object ServerRustModule {
4449
software.amazon.smithy.rust.codegen.core.smithy.ConstrainedModule
4550
}
4651

47-
class ServerModuleDocProvider : ModuleDocProvider {
48-
override fun docsWriter(module: RustModule.LeafModule): Writable? = writable {
49-
docs(
50-
when (module) {
51-
ServerRustModule.Error -> "All error types that operations can return. Documentation on these types is copied from the model."
52-
ServerRustModule.Operation -> "All operations that this crate can perform."
53-
// TODO(ServerTeam): Document this module (I don't have context)
54-
ServerRustModule.OperationShape -> ""
55-
ServerRustModule.Model -> "Data structures used by operation inputs/outputs. Documentation on these types is copied from the model."
56-
ServerRustModule.Input -> "Input structures for operations. Documentation on these types is copied from the model."
57-
ServerRustModule.Output -> "Output structures for operations. Documentation on these types is copied from the model."
58-
ServerRustModule.Types -> "Data primitives referenced by other data types."
59-
ServerRustModule.Server -> "Contains the types that are re-exported from the `aws-smithy-http-server` crate."
60-
ServerRustModule.UnconstrainedModule -> "Unconstrained types for constrained shapes."
61-
ServerRustModule.ConstrainedModule -> "Constrained types for constrained shapes."
62-
else -> TODO("Document this module: $module")
63-
},
52+
class ServerModuleDocProvider(private val codegenContext: ServerCodegenContext) : ModuleDocProvider {
53+
override fun docsWriter(module: RustModule.LeafModule): Writable? {
54+
val strDoc: (String) -> Writable = { str -> writable { docs(escape(str)) } }
55+
return when (module) {
56+
ServerRustModule.Error -> strDoc("All error types that operations can return. Documentation on these types is copied from the model.")
57+
ServerRustModule.Operation -> strDoc("All operations that this crate can perform.")
58+
ServerRustModule.OperationShape -> operationShapeModuleDoc()
59+
ServerRustModule.Model -> strDoc("Data structures used by operation inputs/outputs. Documentation on these types is copied from the model.")
60+
ServerRustModule.Input -> strDoc("Input structures for operations. Documentation on these types is copied from the model.")
61+
ServerRustModule.Output -> strDoc("Output structures for operations. Documentation on these types is copied from the model.")
62+
ServerRustModule.Types -> strDoc("Data primitives referenced by other data types.")
63+
ServerRustModule.Server -> strDoc("Contains the types that are re-exported from the `aws-smithy-http-server` crate.")
64+
ServerRustModule.UnconstrainedModule -> strDoc("Unconstrained types for constrained shapes.")
65+
ServerRustModule.ConstrainedModule -> strDoc("Constrained types for constrained shapes.")
66+
else -> TODO("Document this module: $module")
67+
}
68+
}
69+
70+
private fun operationShapeModuleDoc(): Writable = writable {
71+
val index = TopDownIndex.of(codegenContext.model)
72+
val operations = index.getContainedOperations(codegenContext.serviceShape).toSortedSet(compareBy { it.id })
73+
74+
val firstOperation = operations.first() ?: return@writable
75+
val firstOperationSymbol = codegenContext.symbolProvider.toSymbol(firstOperation)
76+
val firstOperationName = firstOperationSymbol.name.toPascalCase()
77+
val crateName = codegenContext.settings.moduleName.toSnakeCase()
78+
79+
rustTemplate(
80+
"""
81+
/// A collection of types representing each operation defined in the service closure.
82+
///
83+
/// ## Constructing an [`Operation`](#{SmithyHttpServer}::operation::OperationShapeExt)
84+
///
85+
/// To apply middleware to specific operations the [`Operation`](#{SmithyHttpServer}::operation::Operation)
86+
/// API must be used.
87+
///
88+
/// Using the [`OperationShapeExt`](#{SmithyHttpServer}::operation::OperationShapeExt) trait
89+
/// implemented on each ZST we can construct an [`Operation`](#{SmithyHttpServer}::operation::Operation)
90+
/// with appropriate constraints given by Smithy.
91+
///
92+
/// #### Example
93+
///
94+
/// ```no_run
95+
/// use $crateName::operation_shape::$firstOperationName;
96+
/// use #{SmithyHttpServer}::operation::OperationShapeExt;
97+
///
98+
#{HandlerImports:W}
99+
///
100+
#{Handler:W}
101+
///
102+
/// let operation = $firstOperationName::from_handler(handler)
103+
/// .layer(todo!("Provide a layer implementation"));
104+
/// ```
105+
///
106+
/// ## Use as Marker Structs
107+
///
108+
/// The [plugin system](#{SmithyHttpServer}::plugin) also makes use of these
109+
/// [zero-sized types](https://doc.rust-lang.org/nomicon/exotic-sizes.html##zero-sized-types-zsts) (ZSTs) to
110+
/// parameterize [`Plugin`](#{SmithyHttpServer}::plugin::Plugin) implementations. The traits, such as
111+
/// [`OperationShape`](#{SmithyHttpServer}::operation::OperationShape) can be used to provide
112+
/// operation specific information to the [`Layer`](#{Tower}::Layer) being applied.
113+
""".trimIndent(),
114+
"SmithyHttpServer" to
115+
ServerCargoDependency.smithyHttpServer(codegenContext.runtimeConfig).toType(),
116+
"Tower" to ServerCargoDependency.Tower.toType(),
117+
"Handler" to DocHandlerGenerator(codegenContext, firstOperation, "handler", commentToken = "///")::render,
118+
"HandlerImports" to handlerImports(crateName, operations, commentToken = "///"),
64119
)
65120
}
66121
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@ import software.amazon.smithy.rust.codegen.core.util.toPascalCase
1717
import software.amazon.smithy.rust.codegen.server.smithy.ServerCargoDependency
1818

1919
class ServerOperationGenerator(
20-
codegenContext: CodegenContext,
2120
private val operation: OperationShape,
21+
codegenContext: CodegenContext,
2222
) {
2323
private val runtimeConfig = codegenContext.runtimeConfig
2424
private val codegenScope =

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

Lines changed: 0 additions & 75 deletions
This file was deleted.

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

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -257,10 +257,6 @@ open class ServerServiceGenerator(
257257
}
258258
}
259259

260-
rustCrate.withModule(ServerRustModule.OperationShape) {
261-
ServerOperationShapeGenerator(operations, codegenContext).render(this)
262-
}
263-
264260
rustCrate.withModule(RustModule.private("service")) {
265261
ServerServiceGeneratorV2(codegenContext, protocol).render(this)
266262
}

0 commit comments

Comments
 (0)