Unhide new service builder and deprecate the prior

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

@@ -165,6 +165,7 @@ ${operationImplementationStubs(operations)}
     }
 
     private fun renderOperationRegistryStruct(writer: RustWriter) {
+        writer.rust("""##[deprecated(since = "0.52.0", note = "OperationRegistry is part of the deprecated service builder API. Use `$serviceName::builder` instead.")]""")
         writer.rustBlock("pub struct $operationRegistryNameWithArguments") {
             val members = operationNames
                 .mapIndexed { i, operationName -> "$operationName: Op$i" }
@@ -183,6 +184,7 @@ ${operationImplementationStubs(operations)}
      * Renders the `OperationRegistryBuilder` structure, used to build the `OperationRegistry`.
      */
     private fun renderOperationRegistryBuilderStruct(writer: RustWriter) {
+        writer.rust("""##[deprecated(since = "0.52.0", note = "OperationRegistryBuilder is part of the deprecated service builder API. Use `$serviceName::builder` instead.")]""")
         writer.rustBlock("pub struct $operationRegistryBuilderNameWithArguments") {
             val members = operationNames
                 .mapIndexed { i, operationName -> "$operationName: Option<Op$i>" }

design/src/server/instrumentation.md

@@ -53,11 +53,19 @@ Smithy provides an out-the-box middleware which:
 - Opens a DEBUG level span, prior to request handling, including the operation name and request URI and headers.
 - Emits a DEBUG level event, after to request handling, including the response headers and status code.
 
-This is applied by default and can be enabled and disabled by filtering on `aws_smithy_http_server::instrumentation`.
+This is enabled via the `instrument` method provided by the `aws_smithy_http_server::instrumentation::InstrumentExt` trait.
 
-<!-- TODO: Link to it when the logging module is no longer `#[doc(hidden)]` -->
+```rust
+use aws_smithy_http_server::instrumentation::InstrumentExt;
 
-<!-- TODO: Document use of the `InstrumentExt` after the new service builder is released. -->
+let app = PokemonService::builder()
+  .get_pokemon_species(/* handler */)
+  /* ... */
+  .instrument()
+  .build();
+```
+
+<!-- TODO: Link to it when the logging module is no longer `#[doc(hidden)]` -->
 
 ### Example
 

design/src/server/overview.md

@@ -4,6 +4,6 @@ Smithy Rust provides the ability to generate a server whose operations are provi
 
 - [Generating Common Service Code](./code_generation.md)
 - [Generating the Pokémon Service](./pokemon_service.md)
-<!-- - [Middleware](./middleware.md) -->
+- [Middleware](./middleware.md)
 - [Instrumentation](./instrumentation.md)
-<!-- - [The Anatomy of a Service](./anatomy.md) -->
+- [The Anatomy of a Service](./anatomy.md)

rust-runtime/aws-smithy-http-server/examples/pokemon-service/src/bin/pokemon-service-lambda.rs

@@ -6,18 +6,18 @@
 // This program is exported as a binary named `pokemon-service-lambda`.
 use std::sync::Arc;
 
-use aws_smithy_http_server::{routing::LambdaHandler, AddExtensionLayer, Router};
+use aws_smithy_http_server::{routing::LambdaHandler, AddExtensionLayer};
 use pokemon_service::{
-    capture_pokemon, check_health, do_nothing, get_pokemon_species, get_server_statistics, get_storage, setup_tracing,
-    State,
+    capture_pokemon, check_health, do_nothing, get_pokemon_species, get_server_statistics, get_storage,
+    plugin::PrintExt, setup_tracing, State,
 };
-use pokemon_service_server_sdk::operation_registry::OperationRegistryBuilder;
+use pokemon_service_server_sdk::service::PokemonService;
 
 #[tokio::main]
 pub async fn main() {
     setup_tracing();
 
-    let app: Router = OperationRegistryBuilder::default()
+    let app = PokemonService::builder()
         // Build a registry containing implementations to all the operations in the service. These
         // are async functions or async closures that take as input the operation's input and
         // return the operation's output.
@@ -27,15 +27,11 @@ pub async fn main() {
         .capture_pokemon(capture_pokemon)
         .do_nothing(do_nothing)
         .check_health(check_health)
+        // Apply the `PrintPlugin` defined in `plugin.rs`
+        .print()
         .build()
-        .expect("Unable to build operation registry")
-        // Convert it into a router that will route requests to the matching operation
-        // implementation.
-        .into();
-
-    // Setup shared state and middlewares.
-    let shared_state = Arc::new(State::default());
-    let app = app.layer(AddExtensionLayer::new(shared_state));
+        // Setup shared state and middlewares.
+        .layer(&AddExtensionLayer::new(Arc::new(State::default())));
 
     let handler = LambdaHandler::new(app);
     let lambda = lambda_http::run(handler);

rust-runtime/aws-smithy-http-server/examples/pokemon-service/src/bin/pokemon-service-tls.rs

@@ -28,14 +28,14 @@ use std::io::BufReader;
 use std::net::SocketAddr;
 use std::sync::Arc;
 
-use aws_smithy_http_server::{AddExtensionLayer, Router};
+use aws_smithy_http_server::AddExtensionLayer;
 use clap::Parser;
 use futures_util::stream::StreamExt;
 use pokemon_service::{
-    capture_pokemon, check_health, do_nothing, get_pokemon_species, get_server_statistics, get_storage, setup_tracing,
-    State,
+    capture_pokemon, check_health, do_nothing, get_pokemon_species, get_server_statistics, get_storage,
+    plugin::PrintExt, setup_tracing, State,
 };
-use pokemon_service_server_sdk::operation_registry::OperationRegistryBuilder;
+use pokemon_service_server_sdk::service::PokemonService;
 use tokio_rustls::{
     rustls::{Certificate, PrivateKey, ServerConfig},
     TlsAcceptor,
@@ -62,7 +62,7 @@ struct Args {
 pub async fn main() {
     let args = Args::parse();
     setup_tracing();
-    let app: Router = OperationRegistryBuilder::default()
+    let app = PokemonService::builder()
         // Build a registry containing implementations to all the operations in the service. These
         // are async functions or async closures that take as input the operation's input and
         // return the operation's output.
@@ -72,15 +72,11 @@ pub async fn main() {
         .capture_pokemon(capture_pokemon)
         .do_nothing(do_nothing)
         .check_health(check_health)
+        // Apply the `PrintPlugin` defined in `plugin.rs`
+        .print()
         .build()
-        .expect("Unable to build operation registry")
-        // Convert it into a router that will route requests to the matching operation
-        // implementation.
-        .into();
-
-    // Setup shared state and middlewares.
-    let shared_state = Arc::new(State::default());
-    let app = app.layer(AddExtensionLayer::new(shared_state));
+        // Setup shared state and middlewares.
+        .layer(&AddExtensionLayer::new(Arc::new(State::default())));
 
     let addr: SocketAddr = format!("{}:{}", args.address, args.port)
         .parse()

rust-runtime/aws-smithy-http-server/examples/pokemon-service/src/bin/pokemon-service.rs

@@ -6,13 +6,13 @@
 // This program is exported as a binary named `pokemon-service`.
 use std::{net::SocketAddr, sync::Arc};
 
-use aws_smithy_http_server::{AddExtensionLayer, Router};
+use aws_smithy_http_server::AddExtensionLayer;
 use clap::Parser;
 use pokemon_service::{
-    capture_pokemon, check_health, do_nothing, get_pokemon_species, get_server_statistics, get_storage, setup_tracing,
-    State,
+    capture_pokemon, check_health, do_nothing, get_pokemon_species, get_server_statistics, get_storage,
+    plugin::PrintExt, setup_tracing, State,
 };
-use pokemon_service_server_sdk::operation_registry::OperationRegistryBuilder;
+use pokemon_service_server_sdk::service::PokemonService;
 
 #[derive(Parser, Debug)]
 #[clap(author, version, about, long_about = None)]
@@ -29,7 +29,7 @@ struct Args {
 pub async fn main() {
     let args = Args::parse();
     setup_tracing();
-    let app: Router = OperationRegistryBuilder::default()
+    let app = PokemonService::builder()
         // Build a registry containing implementations to all the operations in the service. These
         // are async functions or async closures that take as input the operation's input and
         // return the operation's output.
@@ -39,15 +39,11 @@ pub async fn main() {
         .capture_pokemon(capture_pokemon)
         .do_nothing(do_nothing)
         .check_health(check_health)
+        // Apply the `PrintPlugin` defined in `plugin.rs`
+        .print()
         .build()
-        .expect("Unable to build operation registry")
-        // Convert it into a router that will route requests to the matching operation
-        // implementation.
-        .into();
-
-    // Setup shared state and middlewares.
-    let shared_state = Arc::new(State::default());
-    let app = app.layer(AddExtensionLayer::new(shared_state));
+        // Setup shared state and middlewares.
+        .layer(&AddExtensionLayer::new(Arc::new(State::default())));
 
     // Start the [`hyper::Server`].
     let bind: SocketAddr = format!("{}:{}", args.address, args.port)

rust-runtime/aws-smithy-http-server/examples/pokemon-service/src/lib.rs

@@ -19,7 +19,6 @@ use pokemon_service_server_sdk::{error, input, model, model::CapturingPayload, o
 use rand::Rng;
 use tracing_subscriber::{prelude::*, EnvFilter};
 
-#[doc(hidden)]
 pub mod plugin;
 
 const PIKACHU_ENGLISH_FLAVOR_TEXT: &str =

rust-runtime/aws-smithy-http-server/examples/pokemon-service/src/plugin.rs

@@ -3,6 +3,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+//! Provides an example [`Plugin`] implementation - [`PrintPlugin`].
+
 use aws_smithy_http_server::{
     operation::{Operation, OperationShape},
     plugin::{Pluggable, Plugin},
@@ -11,7 +13,7 @@ use tower::{layer::util::Stack, Layer, Service};
 
 use std::task::{Context, Poll};
 
-/// A [`Service`] that adds a print log.
+/// A [`Service`] that prints a given string.
 #[derive(Clone, Debug)]
 pub struct PrintService<S> {
     inner: S,

rust-runtime/aws-smithy-http-server/src/lib.rs

@@ -13,19 +13,14 @@ pub(crate) mod macros;
 pub mod body;
 pub(crate) mod error;
 pub mod extension;
-#[doc(hidden)]
 pub mod instrumentation;
-#[doc(hidden)]
 pub mod operation;
-#[doc(hidden)]
 pub mod plugin;
 #[doc(hidden)]
 pub mod protocols;
 #[doc(hidden)]
 pub mod rejection;
-#[doc(hidden)]
 pub mod request;
-#[doc(hidden)]
 pub mod response;
 pub mod routing;
 #[doc(hidden)]
@@ -38,6 +33,7 @@ pub mod routers;
 pub(crate) use self::error::Error;
 pub use self::extension::Extension;
 #[doc(inline)]
+#[allow(deprecated)]
 pub use self::routing::Router;
 #[doc(inline)]
 pub use tower_http::add_extension::{AddExtension, AddExtensionLayer};

rust-runtime/aws-smithy-http-server/src/operation/mod.rs

@@ -201,7 +201,7 @@ pub struct Operation<S, L = Identity> {
 }
 
 impl<S, L> Operation<S, L> {
-    /// Applies a [`Layer`] to the operation _after_ it has been upgraded via [`Operation::upgrade`].
+    /// Applies a [`Layer`](tower::Layer) to the operation _after_ it has been upgraded via [`Operation::upgrade`].
     pub fn layer<NewL>(self, layer: NewL) -> Operation<S, Stack<L, NewL>> {
         Operation {
             inner: self.inner,

rust-runtime/aws-smithy-http-server/src/routing/mod.rs

@@ -62,6 +62,10 @@ pub use self::{future::RouterFuture, into_make_service::IntoMakeService, route::
 /// [awsJson1.1]: https://awslabs.github.io/smithy/1.0/spec/aws/aws-json-1_1-protocol.html
 /// [endpoint trait]: https://awslabs.github.io/smithy/1.0/spec/core/endpoint-traits.html#endpoint-trait
 #[derive(Debug)]
+#[deprecated(
+    since = "0.52.0",
+    note = "OperationRegistry is part of the deprecated service builder API. This type no longer appears in the public API."
+)]
 pub struct Router<B = Body> {
     routes: Routes<B>,
 }
@@ -81,6 +85,7 @@ enum Routes<B = Body> {
     AwsJson1_1(RoutingService<AwsJsonRouter<Route<B>>, AwsJson1_1>),
 }
 
+#[allow(deprecated)]
 impl<B> Clone for Router<B> {
     fn clone(&self) -> Self {
         match &self.routes {
@@ -100,6 +105,7 @@ impl<B> Clone for Router<B> {
     }
 }
 
+#[allow(deprecated)]
 impl<B> Router<B>
 where
     B: Send + 'static,
@@ -249,6 +255,7 @@ where
     }
 }
 
+#[allow(deprecated)]
 impl<B> Service<Request<B>> for Router<B>
 where
     B: Send + 'static,
@@ -277,6 +284,7 @@ where
 }
 
 #[cfg(test)]
+#[allow(deprecated)]
 mod rest_tests {
     use super::*;
     use crate::{
@@ -503,6 +511,7 @@ mod rest_tests {
     }
 }
 
+#[allow(deprecated)]
 #[cfg(test)]
 mod awsjson_tests {
     use super::rest_tests::{get_body_as_string, req};

rust-runtime/inlineable/src/server_operation_handler_trait.rs

@@ -14,12 +14,17 @@ use tower::Service;
 
 /// Struct that holds a handler, that is, a function provided by the user that implements the
 /// Smithy operation.
+#[deprecated(
+    since = "0.52.0",
+    note = "OperationHandler is part of the older service builder API. This type no longer appears in the public API."
+)]
 pub struct OperationHandler<H, B, R, I> {
     handler: H,
     #[allow(clippy::type_complexity)]
     _marker: PhantomData<(B, R, I)>,
 }
 
+#[allow(deprecated)]
 impl<H, B, R, I> Clone for OperationHandler<H, B, R, I>
 where
     H: Clone,
@@ -33,13 +38,19 @@ where
 }
 
 /// Construct an [`OperationHandler`] out of a function implementing the operation.
+#[allow(deprecated)]
+#[deprecated(
+    since = "0.52.0",
+    note = "OperationHandler is part of the older service builder API. This type no longer appears in the public API."
+)]
 pub fn operation<H, B, R, I>(handler: H) -> OperationHandler<H, B, R, I> {
     OperationHandler {
         handler,
         _marker: PhantomData,
     }
 }
 
+#[allow(deprecated)]
 impl<H, B, R, I> Service<Request<B>> for OperationHandler<H, B, R, I>
 where
     H: Handler<B, R, I>,
@@ -80,6 +91,10 @@ pub(crate) mod sealed {
     impl HiddenTrait for Hidden {}
 }
 
+#[deprecated(
+    since = "0.52.0",
+    note = "The inlineable Handler is part of the deprecated service builder API. This type no longer appears in the public API."
+)]
 #[async_trait]
 pub trait Handler<B, T, Fut>: Clone + Send + Sized + 'static {
     #[doc(hidden)]