Unverified Commit bf3fbc2e authored by Harry Barber's avatar Harry Barber Committed by GitHub
Browse files

Add "Anatomy of a Service" documentation (#1782) 

* Rust documentation improvements

* Add "Anatomy of a Service" documentation
parent 94a991cd

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

+2 −2
Original line number Diff line number Diff line
@@ -113,7 +113,7 @@ class ServerServiceGeneratorV2( 
                """

                /// Sets the [`$structName`](crate::operation_shape::$structName) operation.

                ///

                /// This should be a closure satisfying the [`Handler`](#{SmithyHttpServer}::operation::Handler) trait.

                /// This should be an async function satisfying the [`Handler`](#{SmithyHttpServer}::operation::Handler) trait.

                /// See the [operation module documentation](#{SmithyHttpServer}::operation) for more information.

                pub fn $fieldName<H, NewExts>(self, value: H) -> $builderName<#{HandlerSetterGenerics:W}>

                where
@@ -312,7 +312,7 @@ class ServerServiceGeneratorV2( 
                    #{SmithyHttpServer}::routing::IntoMakeService::new(self)

                }



                /// Applies a layer uniformly to all routes.

                /// Applies a [`Layer`](#{Tower}::Layer) uniformly to all routes.

                pub fn layer<L>(self, layer: &L) -> $serviceName<L::Service>

                where

                    L: #{Tower}::Layer<S>

design/src/SUMMARY.md

+1 −0
Original line number Diff line number Diff line
@@ -18,6 +18,7 @@ 
  - [Generating Common Service Code](./server/code_generation.md)

  - [Generating the Pokémon Service](./server/pokemon_service.md)

  - [Instrumentation](./server/instrumentation.md)

  <!-- - [The Anatomy of a Service](./server/anatomy.md) -->



- [RFCs](./rfcs/overview.md)

  - [RFC-0001: Sharing configuration between multiple clients](./rfcs/rfc0001_shared_config.md)

design/src/server/anatomy.md

0 → 100644
+880 −0

File added.

Preview size limit exceeded, changes collapsed.

design/src/server/overview.md

+1 −0
Original line number Diff line number Diff line
@@ -5,3 +5,4 @@ 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)

- [Instrumentation](./instrumentation.md)

<!-- - [The Anatomy of a Service](./anatomy.md) -->

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

+18 −14
Original line number Diff line number Diff line
@@ -3,7 +3,13 @@ 
 * SPDX-License-Identifier: Apache-2.0

 */



use aws_smithy_http_server::plugin::Plugin;

use aws_smithy_http_server::{

    operation::{Operation, OperationShape},

    plugin::{Pluggable, Plugin},

};

use tower::{layer::util::Stack, Layer, Service};



use std::task::{Context, Poll};



/// A [`Service`](tower::Service) that adds a print log.

#[derive(Clone, Debug)]
@@ -12,15 +18,15 @@ pub struct PrintService<S> { 
    name: &'static str,

}



impl<R, S> tower::Service<R> for PrintService<S>

impl<R, S> Service<R> for PrintService<S>

where

    S: tower::Service<R>,

    S: Service<R>,

{

    type Response = S::Response;

    type Error = S::Error;

    type Future = S::Future;



    fn poll_ready(&mut self, cx: &mut std::task::Context<'_>) -> std::task::Poll<Result<(), Self::Error>> {

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {

        self.inner.poll_ready(cx)

    }
@@ -35,7 +41,7 @@ where 
pub struct PrintLayer {

    name: &'static str,

}

impl<S> tower::Layer<S> for PrintLayer {

impl<S> Layer<S> for PrintLayer {

    type Service = PrintService<S>;



    fn layer(&self, service: S) -> Self::Service {
@@ -46,26 +52,24 @@ impl<S> tower::Layer<S> for PrintLayer { 
    }

}



/// A [`Plugin`]() for a service builder to add a [`PrintLayer`] over operations.

/// A [`Plugin`] for a service builder to add a [`PrintLayer`] over operations.

#[derive(Debug)]

pub struct PrintPlugin;



impl<P, Op, S, L> Plugin<P, Op, S, L> for PrintPlugin

where

    Op: aws_smithy_http_server::operation::OperationShape,

    Op: OperationShape,

{

    type Service = S;

    type Layer = tower::layer::util::Stack<L, PrintLayer>;

    type Layer = Stack<L, PrintLayer>;



    fn map(

        &self,

        input: aws_smithy_http_server::operation::Operation<S, L>,

    ) -> aws_smithy_http_server::operation::Operation<Self::Service, Self::Layer> {

    fn map(&self, input: Operation<S, L>) -> Operation<Self::Service, Self::Layer> {

        input.layer(PrintLayer { name: Op::NAME })

    }

}



/// An extension to service builders to add the `print()` function.

pub trait PrintExt: aws_smithy_http_server::plugin::Pluggable<PrintPlugin> {

pub trait PrintExt: Pluggable<PrintPlugin> {

    /// Causes all operations to print the operation name when called.

    ///

    /// This works by applying the [`PrintPlugin`].
@@ -77,4 +81,4 @@ pub trait PrintExt: aws_smithy_http_server::plugin::Pluggable<PrintPlugin> { 
    }

}



impl<Builder> PrintExt for Builder where Builder: aws_smithy_http_server::plugin::Pluggable<PrintPlugin> {}
 
impl<Builder> PrintExt for Builder where Builder: Pluggable<PrintPlugin> {}