p3-http: improve docs

Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

Author: rvolosatovs

crates/wasi-http/src/p3/body.rs

@@ -42,6 +42,7 @@ pub(crate) enum Body {
 }
 
 impl Body {
+    /// Implementation of `consume-body` shared between requests and responses
     pub(crate) fn consume<T>(
         self,
         mut store: Access<'_, T, WasiHttp>,
@@ -105,6 +106,7 @@ impl Body {
         }
     }
 
+    /// Implementation of `drop` shared between requests and responses
     pub(crate) fn drop(self, mut store: impl AsContextMut) {
         if let Body::Guest {
             contents_rx,
@@ -120,7 +122,8 @@ impl Body {
     }
 }
 
-pub(crate) enum GuestBodyKind {
+/// The kind of body, used for error reporting
+pub(crate) enum BodyKind {
     Request,
     Response,
 }
@@ -141,20 +144,22 @@ impl ContentLength {
     }
 }
 
+/// [StreamConsumer] implementation for bodies originating in the guest.
 struct GuestBodyConsumer {
     contents_tx: PollSender<Result<Bytes, ErrorCode>>,
     result_tx: Option<oneshot::Sender<Result<(), ErrorCode>>>,
     content_length: Option<ContentLength>,
-    kind: GuestBodyKind,
+    kind: BodyKind,
     // `true` when the other side of `contents_tx` was unexpectedly closed
     closed: bool,
 }
 
 impl GuestBodyConsumer {
+    /// Constructs the approprite body size error given the [BodyKind]
     fn body_size_error(&self, n: Option<u64>) -> ErrorCode {
         match self.kind {
-            GuestBodyKind::Request => ErrorCode::HttpRequestBodySize(n),
-            GuestBodyKind::Response => ErrorCode::HttpResponseBodySize(n),
+            BodyKind::Request => ErrorCode::HttpRequestBodySize(n),
+            BodyKind::Response => ErrorCode::HttpResponseBodySize(n),
         }
     }
 
@@ -235,20 +240,22 @@ impl<D> StreamConsumer<D> for GuestBodyConsumer {
     }
 }
 
+/// [http_body::Body] implementation for bodies originating in the guest.
 pub(crate) struct GuestBody {
     contents_rx: Option<mpsc::Receiver<Result<Bytes, ErrorCode>>>,
     trailers_rx: Option<oneshot::Receiver<Result<Option<Arc<http::HeaderMap>>, ErrorCode>>>,
     content_length: Option<u64>,
 }
 
 impl GuestBody {
+    /// Construct a new [GuestBody]
     pub(crate) fn new<T: 'static>(
         mut store: impl AsContextMut<Data = T>,
         contents_rx: Option<StreamReader<u8>>,
         trailers_rx: FutureReader<Result<Option<Resource<Trailers>>, ErrorCode>>,
         result_tx: oneshot::Sender<Result<(), ErrorCode>>,
         content_length: Option<u64>,
-        kind: GuestBodyKind,
+        kind: BodyKind,
         getter: fn(&mut T) -> WasiHttpCtxView<'_>,
     ) -> Self {
         let (trailers_http_tx, trailers_http_rx) = oneshot::channel();
@@ -290,10 +297,15 @@ impl http_body::Body for GuestBody {
         cx: &mut Context<'_>,
     ) -> Poll<Option<Result<http_body::Frame<Self::Data>, Self::Error>>> {
         if let Some(contents_rx) = self.contents_rx.as_mut() {
+            // `contents_rx` has not been closed yet, poll it
             while let Some(res) = ready!(contents_rx.poll_recv(cx)) {
                 match res {
                     Ok(buf) => {
                         if let Some(n) = self.content_length.as_mut() {
+                            // Substract frame length from `content_length`,
+                            // [GuestBodyConsumer] already performs the validation, so
+                            // just keep count as optimization for
+                            // `is_end_stream` and `size_hint`
                             *n = n.saturating_sub(buf.len().try_into().unwrap_or(u64::MAX));
                         }
                         return Poll::Ready(Some(Ok(http_body::Frame::data(buf))));
@@ -303,14 +315,17 @@ impl http_body::Body for GuestBody {
                     }
                 }
             }
+            // Record that `contents_rx` is closed
             self.contents_rx = None;
         }
 
         let Some(trailers_rx) = self.trailers_rx.as_mut() else {
+            // `trailers_rx` has already terminated - this is the end of stream
             return Poll::Ready(None);
         };
 
         let res = ready!(Pin::new(trailers_rx).poll(cx));
+        // Record that `trailers_rx` has terminated
         self.trailers_rx = None;
         match res {
             Ok(Ok(Some(trailers))) => Poll::Ready(Some(Ok(http_body::Frame::trailers(
@@ -328,14 +343,18 @@ impl http_body::Body for GuestBody {
                 || !contents_rx.is_closed()
                 || self.content_length.is_some_and(|n| n > 0)
             {
+                // `contents_rx` might still produce data frames
                 return false;
             }
         }
         if let Some(trailers_rx) = self.trailers_rx.as_ref() {
             if !trailers_rx.is_terminated() {
+                // `trailers_rx` has not terminated yet
                 return false;
             }
         }
+
+        // no data left
         return true;
     }
 
@@ -348,6 +367,7 @@ impl http_body::Body for GuestBody {
     }
 }
 
+/// [http_body::Body] that has been consumed.
 pub(crate) struct ConsumedBody;
 
 impl http_body::Body for ConsumedBody {
@@ -372,6 +392,7 @@ impl http_body::Body for ConsumedBody {
     }
 }
 
+/// [FutureConsumer] implementation for trailers originating in the guest.
 struct GuestTrailerConsumer<T> {
     tx: Option<oneshot::Sender<Result<Option<Arc<HeaderMap>>, ErrorCode>>>,
     getter: fn(&mut T) -> WasiHttpCtxView<'_>,
@@ -409,6 +430,7 @@ where
     }
 }
 
+/// [StreamProducer] implementation for bodies originating in the host.
 struct HostBodyStreamProducer<T> {
     body: BoxBody<Bytes, ErrorCode>,
     trailers: Option<oneshot::Sender<Result<Option<Resource<Trailers>>, ErrorCode>>>,
@@ -447,6 +469,8 @@ where
             let cap = match dst.remaining(&mut store).map(NonZeroUsize::new) {
                 Some(Some(cap)) => Some(cap),
                 Some(None) => {
+                    // On 0-length the best we can do is check that underlying stream has not
+                    // reached the end yet
                     if self.body.is_end_stream() {
                         break 'result Ok(None);
                     } else {
@@ -463,11 +487,13 @@ where
                                 let n = frame.len();
                                 let cap = cap.into();
                                 if n > cap {
+                                    // data frame does not fit in destination, fill it and buffer the rest
                                     dst.set_buffer(Cursor::new(frame.split_off(cap)));
                                     let mut dst = dst.as_direct(store, cap);
                                     dst.remaining().copy_from_slice(&frame);
                                     dst.mark_written(cap);
                                 } else {
+                                    // copy the whole frame into the destination
                                     let mut dst = dst.as_direct(store, n);
                                     dst.remaining()[..n].copy_from_slice(&frame);
                                     dst.mark_written(n);

crates/wasi-http/src/p3/host/handler.rs

@@ -1,6 +1,6 @@
 use crate::p3::bindings::http::handler::{Host, HostWithStore};
 use crate::p3::bindings::http::types::{ErrorCode, Request, Response};
-use crate::p3::body::{Body, ConsumedBody, GuestBody, GuestBodyKind};
+use crate::p3::body::{Body, BodyKind, ConsumedBody, GuestBody};
 use crate::p3::{HttpError, HttpResult, WasiHttp, WasiHttpCtxView, get_content_length};
 use anyhow::Context as _;
 use core::pin::Pin;
@@ -135,6 +135,7 @@ impl HostWithStore for WasiHttp {
                     result_tx,
                 } => {
                     let (http_result_tx, http_result_rx) = oneshot::channel();
+                    // `Content-Length` header value is validated in `fields` implementation
                     let content_length = get_content_length(&headers)
                         .map_err(|err| ErrorCode::InternalError(Some(format!("{err:#}"))))?;
                     _ = result_tx.send(Box::new(async move {
@@ -149,7 +150,7 @@ impl HostWithStore for WasiHttp {
                         trailers_rx,
                         http_result_tx,
                         content_length,
-                        GuestBodyKind::Request,
+                        BodyKind::Request,
                         getter,
                     )
                     .with_state(io_task_rx)
@@ -199,6 +200,7 @@ impl HostWithStore for WasiHttp {
                 req,
                 options.as_deref().copied(),
                 Box::new(async {
+                    // Forward the response processing result to `WasiHttpCtx` implementation
                     let Ok(fut) = res_result_rx.await else {
                         return Ok(());
                     };

crates/wasi-http/src/p3/host/types.rs

@@ -315,7 +315,6 @@ impl HostRequestWithStore for WasiHttp {
             let (result_tx, result_rx) = oneshot::channel();
             let WasiHttpCtxView { table, .. } = store.get();
             let headers = delete_fields(table, headers)?;
-            // `Content-Length` header value is validated in `fields` implementation
             let options = options
                 .map(|options| delete_request_options(table, options))
                 .transpose()?;

crates/wasi-http/src/p3/mod.rs

@@ -89,6 +89,18 @@ pub trait WasiHttpCtx: Send {
     }
 
     /// Send an outgoing request.
+    ///
+    /// This implementation will be used by the `wasi:http/handler#handle` implementation.
+    ///
+    /// The specified [Future] `fut` can be used to communicate
+    /// a request processing error, if any, to the constructor of the request.
+    /// For example, if the request was constructed via `wasi:http/types.request#new`,
+    /// a result sent on `fut` will be forwarded to the guest on the future handle returned.
+    ///
+    /// The returned [Future] can be used to communicate
+    /// a request processing error, if any, to the constructor of the request.
+    /// For example, if the request was constructed via `wasi:http/types.request#new`,
+    /// a result resolved from it will be forwarded to the guest on the future handle returned.
     #[cfg(feature = "default-send-request")]
     fn send_request(
         &mut self,

crates/wasi-http/src/p3/proxy.rs

@@ -5,7 +5,7 @@ use anyhow::Context as _;
 use wasmtime::component::Accessor;
 
 impl Proxy {
-    /// Call `handle` on [Proxy] getting a [Future] back.
+    /// Call `wasi:http/handler#handle` on [Proxy] getting a [Response] back.
     pub async fn handle(
         &self,
         store: &Accessor<impl WasiHttpView>,

crates/wasi-http/src/p3/request.rs

@@ -41,7 +41,7 @@ pub struct Request {
 impl Request {
     /// Construct a new [Request]
     ///
-    /// This returns a [Future] that the guest will use to communicate
+    /// This returns a [Future] that the will be used to communicate
     /// a request processing error, if any.
     pub fn new(
         method: Method,
@@ -78,7 +78,7 @@ impl Request {
 
     /// Construct a new [Request] from [http::Request].
     ///
-    /// This returns a [Future] that the guest will use to communicate
+    /// This returns a [Future] that will be used to communicate
     /// a request processing error, if any.
     pub fn from_http<T>(
         req: http::Request<T>,
@@ -121,6 +121,11 @@ impl Request {
 ///
 /// This implementation is used by the `wasi:http/handler` interface
 /// default implementation.
+///
+/// The returned [Future] can be used to communicate
+/// a request processing error, if any, to the constructor of the request.
+/// For example, if the request was constructed via `wasi:http/types.request#new`,
+/// a result resolved from it will be forwarded to the guest on the future handle returned.
 #[cfg(feature = "default-send-request")]
 pub async fn default_send_request(
     mut req: http::Request<impl http_body::Body<Data = Bytes, Error = ErrorCode> + Send + 'static>,
@@ -202,7 +207,10 @@ pub async fn default_send_request(
         {
             return Err(dns_error("address not available".to_string(), 0));
         }
-        Ok(Err(..)) => return Err(ErrorCode::ConnectionRefused),
+        Ok(Err(err)) => {
+            tracing::warn!(?err, "connection refused");
+            return Err(ErrorCode::ConnectionRefused);
+        }
         Err(..) => return Err(ErrorCode::ConnectionTimeout),
     };
     let stream = if use_tls {

crates/wasi-http/src/p3/response.rs

@@ -1,5 +1,5 @@
 use crate::p3::bindings::http::types::ErrorCode;
-use crate::p3::body::{Body, ConsumedBody, GuestBody, GuestBodyKind};
+use crate::p3::body::{Body, BodyKind, ConsumedBody, GuestBody};
 use crate::p3::{WasiHttpView, get_content_length};
 use anyhow::Context as _;
 use bytes::Bytes;
@@ -40,7 +40,9 @@ impl Response {
     /// Convert [Response] into [http::Response].
     ///
     /// The specified [Future] `fut` can be used to communicate
-    /// a response processing error, if any, to the guest.
+    /// a response processing error, if any, to the constructor of the response.
+    /// For example, if the response was constructed via `wasi:http/types.response#new`,
+    /// a result sent on `fut` will be forwarded to the guest on the future handle returned.
     pub fn into_http<T: WasiHttpView + 'static>(
         self,
         store: impl AsContextMut<Data = T>,
@@ -55,6 +57,7 @@ impl Response {
                 result_tx,
             } => {
                 let (http_result_tx, http_result_rx) = oneshot::channel();
+                // `Content-Length` header value is validated in `fields` implementation
                 let content_length =
                     get_content_length(&res.headers).context("failed to parse `content-length`")?;
                 _ = result_tx.send(Box::new(async move {
@@ -69,7 +72,7 @@ impl Response {
                     trailers_rx,
                     http_result_tx,
                     content_length,
-                    GuestBodyKind::Response,
+                    BodyKind::Response,
                     T::http,
                 )
                 .boxed()