Add or update comments on the important types

smithy-lang · Oct 25, 2022 · 7340d64 · 7340d64
1 parent 303cc38
commit 7340d64
Show file tree

Hide file tree

Showing 5 changed files with 25 additions and 8 deletions.
diff --git a/rust-runtime/aws-smithy-http-server-python/examples/mypy.ini b/rust-runtime/aws-smithy-http-server-python/examples/mypy.ini
@@ -1,5 +1,2 @@
 [mypy]
 strict = True
-
-; [mypy-libpokemon_service_server_sdk.*]
-; ignore_missing_imports = True
diff --git a/rust-runtime/aws-smithy-http-server-python/src/middleware/handler.rs b/rust-runtime/aws-smithy-http-server-python/src/middleware/handler.rs
@@ -15,8 +15,10 @@ use crate::util::func_metadata;
 
 use super::{PyMiddlewareError, PyRequest, PyResponse};
 
+// PyNextInner represents the inner service Tower layer applied to.
 type PyNextInner = BoxService<Request<Body>, Response<BoxBody>, BoxError>;
 
+// PyNext wraps inner Tower service and makes it calleble from Python.
 #[pyo3::pyclass]
 struct PyNext(Option<PyNextInner>);
 
@@ -25,13 +27,24 @@ impl PyNext {
         Self(Some(inner))
     }
 
+    // Consumes self by taking the inner Tower service.
+    // This method would have been `into_inner(self) -> PyNextInner`
+    // but we can't do that because we are crossing Python boundary.
     fn take_inner(&mut self) -> Option<PyNextInner> {
         self.0.take()
     }
 }
 
 #[pyo3::pymethods]
 impl PyNext {
+    // Calls the inner Tower service with the `Request` that is passed from Python.
+    // It returns a coroutine to be awaited on the Python to complete the call.
+    // Note that it takes wrapped objects from both `PyRequest` and `PyNext`,
+    // so after calling `next`, consumer can't access to the `Request` or
+    // can't call the `next` again, this basically emulates consuming `self` and `Request`,
+    // but since we are crossing Python boundary we can't express it in natural Rust terms.
+    //
+    // Naming the method `__call__` allows `next` to be called like `next(...)`.
     fn __call__<'p>(&'p mut self, py: Python<'p>, py_req: Py<PyRequest>) -> PyResult<&'p PyAny> {
         let req = py_req
             .borrow_mut(py)
@@ -71,6 +84,8 @@ impl PyMiddlewareHandler {
         })
     }
 
+    // Calls pure-Python middleware handler with given `Request` and the next Tower service
+    // and returns the `Response` that returned from the pure-Python handler.
     pub async fn call(
         self,
         req: Request<Body>,
@@ -87,10 +102,10 @@ impl PyMiddlewareHandler {
                     let py_handler: &PyFunction = handler.extract(py)?;
                     let output = py_handler.call1((py_req, py_next))?;
                     pyo3_asyncio::tokio::into_future(output)
-                })
+                })?
+                .await
             })
             .await?
-            .await?
         } else {
             Python::with_gil(|py| {
                 let py_handler: &PyFunction = handler.extract(py)?;

diff --git a/rust-runtime/aws-smithy-http-server-python/src/middleware/layer.rs b/rust-runtime/aws-smithy-http-server-python/src/middleware/layer.rs
@@ -25,8 +25,7 @@ use crate::PyMiddlewareException;
 
 /// Tower [Layer] implementation of Python middleware handling.
 ///
-/// Middleware stored in the `handlers` attribute will be executed, in order,
-/// inside an async Tower middleware.
+/// Middleware stored in the `handler` attribute will be executed inside an async Tower middleware.
 #[derive(Debug, Clone)]
 pub struct PyMiddlewareLayer<P> {
     handler: PyMiddlewareHandler,
@@ -60,7 +59,7 @@ where
     }
 }
 
-// Tower [Service] wrapping the Python middleware [Layer].
+/// Tower [Service] wrapping the Python middleware [Layer].
 #[derive(Clone, Debug)]
 pub struct PyMiddlewareService<S> {
     inner: S,

diff --git a/rust-runtime/aws-smithy-http-server-python/src/middleware/request.rs b/rust-runtime/aws-smithy-http-server-python/src/middleware/request.rs
@@ -35,6 +35,9 @@ impl PyRequest {
         }
     }
 
+    // Consumes self by taking the inner Request.
+    // This method would have been `into_inner(self) -> Request<Body>`
+    // but we can't do that because we are crossing Python boundary.
     pub fn take_inner(&mut self) -> Option<Request<Body>> {
         let parts = self.parts.take()?;
         let body = std::mem::replace(&mut self.body, Arc::new(Mutex::new(None)));

diff --git a/rust-runtime/aws-smithy-http-server-python/src/middleware/response.rs b/rust-runtime/aws-smithy-http-server-python/src/middleware/response.rs
@@ -34,6 +34,9 @@ impl PyResponse {
         }
     }
 
+    // Consumes self by taking the inner Response.
+    // This method would have been `into_inner(self) -> Response<BoxBody>`
+    // but we can't do that because we are crossing Python boundary.
     pub fn take_inner(&mut self) -> Option<Response<BoxBody>> {
         let parts = self.parts.take()?;
         let body = std::mem::replace(&mut self.body, Arc::new(Mutex::new(None)));