docs, fixes, minor tweaks

pchickey · pchickey · commit 5d82cd8132d4 · 2025-10-15T14:57:38.000-07:00
diff --git a/examples/complex_http_client.rs b/examples/complex_http_client.rs
@@ -86,7 +86,7 @@ async fn main() -> Result<()> {
     }
 
     let body = if args.body {
-        Body::from_input_stream(wstd::io::stdin().into_inner()).into_boxed_body()
+        Body::from_try_stream(wstd::io::stdin().into_inner().into_stream()).into_boxed_body()
     } else {
         Body::empty().into_boxed_body()
     };
diff --git a/examples/http_client.rs b/examples/http_client.rs
@@ -73,7 +73,7 @@ async fn main() -> Result<()> {
     // Send the request.
 
     let body = if args.body {
-        Body::from_input_stream(wstd::io::stdin().into_inner())
+        Body::from_try_stream(wstd::io::stdin().into_inner().into_stream())
     } else {
         Body::empty()
     };
diff --git a/examples/http_server.rs b/examples/http_server.rs
@@ -1,6 +1,7 @@
 use anyhow::{Context, Result};
 use futures_lite::stream::once_future;
 use http_body_util::{BodyExt, StreamBody};
+use std::convert::Infallible;
 use wstd::http::body::{Body, Bytes, Frame};
 use wstd::http::{Error, HeaderMap, Request, Response, StatusCode};
 use wstd::time::{Duration, Instant};
@@ -55,7 +56,7 @@ async fn http_wait_body(_request: Request<Body>) -> Result<Response<Body>> {
 
         // Compute how long we slept for.
         let elapsed = Instant::now().duration_since(now).as_millis();
-        Ok(Bytes::from(format!("slept for {elapsed} millis\n")))
+        Ok::<_, Infallible>(Bytes::from(format!("slept for {elapsed} millis\n")))
     };
 
     Ok(Response::new(Body::from_try_stream(once_future(body))))
diff --git a/macro/src/lib.rs b/macro/src/lib.rs
@@ -93,19 +93,18 @@ pub fn attr_macro_test(_attr: TokenStream, item: TokenStream) -> TokenStream {
 /// ```ignore
 /// #[wstd::http_server]
 /// async fn main(request: Request<Body>) -> Result<Response<Body>> {
-///     Ok(Response::new("Hello!\n".into_body()))
+///     Ok(Response::new("Hello!\n".into()))
 /// }
 /// ```
 #[proc_macro_attribute]
 pub fn attr_macro_http_server(_attr: TokenStream, item: TokenStream) -> TokenStream {
     let input = parse_macro_input!(item as ItemFn);
 
-    if input.sig.asyncness.is_none() {
-        return quote_spanned! { input.sig.fn_token.span()=>
-            compile_error!("fn must be `async fn`");
-        }
-        .into();
-    }
+    let (run_async, run_await) = if input.sig.asyncness.is_some() {
+        (quote!(async), quote!(.await))
+    } else {
+        (quote!(), quote!())
+    };
 
     let output = &input.sig.output;
     let inputs = &input.sig.inputs;
@@ -130,14 +129,14 @@ pub fn attr_macro_http_server(_attr: TokenStream, item: TokenStream) -> TokenStr
                 response_out: ::wstd::__internal::wasip2::http::types::ResponseOutparam
             ) {
                 #(#attrs)*
-                #vis async fn __run(#inputs) #output {
+                #vis #run_async fn __run(#inputs) #output {
                     #body
                 }
 
                 let responder = ::wstd::http::server::Responder::new(response_out);
                 ::wstd::runtime::block_on(async move {
                     match ::wstd::http::request::try_from_incoming(request) {
-                        Ok(request) => match __run(request).await {
+                        Ok(request) => match __run(request) #run_await {
                             Ok(response) => { responder.respond(response).await.unwrap() },
                             Err(err) => responder.fail(err).unwrap(),
                         }
diff --git a/src/http/body.rs b/src/http/body.rs
@@ -34,10 +34,14 @@ pub mod util {
 ///   from strings.
 /// * `Body::from_json` for a `Body` from a `Serialize` (requires feature
 ///   `json`)
+/// * `From<AsyncInputStream>` for a `Body` with contents given by the
+///   contents of a WASI input-stream.
 /// * `Body::from_stream` or `Body::from_try_stream` for a `Body` from a
 ///   `Stream` of `Into<Bytes>`
 ///
-/// Consume
+/// Consume this HTTP body using:
+///
+///
 #[derive(Debug)]
 pub struct Body(BodyInner);
 
@@ -107,6 +111,10 @@ impl Body {
         }
     }
 
+    /// Convert this `Body` into an `UnsyncBoxBody<Bytes, Error>`, which
+    /// exists to implement the `http_body::Body` trait. Consume the contents
+    /// using `http_body_utils::BodyExt`, or anywhere else an impl of
+    /// `http_body::Body` is accepted.
     pub fn into_boxed_body(self) -> UnsyncBoxBody<Bytes, Error> {
         fn map_e(_: std::convert::Infallible) -> Error {
             unreachable!()
@@ -121,6 +129,9 @@ impl Body {
         }
     }
 
+    /// Collect the entire contents of this `Body`, and expose them as a
+    /// byte slice. This async fn will be pending until the entire `Body` is
+    /// copied into memory, or an error occurs.
     pub async fn contents(&mut self) -> Result<&[u8], Error> {
         match &mut self.0 {
             BodyInner::Complete { ref data, .. } => Ok(data.as_ref()),
@@ -149,6 +160,11 @@ impl Body {
         }
     }
 
+    /// Get a value for the length of this `Body`'s content, in bytes, if
+    /// known. This value can come from either the Content-Length header
+    /// recieved in the incoming request or response assocated with the body,
+    /// or be provided by an exact `http_body::Body::size_hint` if the `Body`
+    /// is constructed from an `http_body::Body` impl.
     pub fn content_length(&self) -> Option<u64> {
         match &self.0 {
             BodyInner::Boxed(b) => b.size_hint().exact(),
@@ -165,16 +181,25 @@ impl Body {
         })
     }
 
+    /// Collect the entire contents of this `Body`, and expose them as a
+    /// string slice. This async fn will be pending until the entire `Body` is
+    /// copied into memory, or an error occurs. Additonally errors if the
+    /// contents of the `Body` were not a utf-8 encoded string.
     pub async fn str_contents(&mut self) -> Result<&str, Error> {
         let bs = self.contents().await?;
         std::str::from_utf8(bs).context("decoding body contents as string")
     }
 
+    /// Construct a `Body` by serializing a type to json. Can fail with a
+    /// `serde_json::Error` if serilization fails.
     #[cfg(feature = "json")]
     pub fn from_json<T: serde::Serialize>(data: &T) -> Result<Self, serde_json::Error> {
         Ok(Self::from(serde_json::to_vec(data)?))
     }
 
+    /// Collect the entire contents of this `Body`, and deserialize them from
+    /// json. Can fail if the body contents are not utf-8 encoded, are not
+    /// valid json, or the json is not accepted by the `serde::Deserialize` impl.
     #[cfg(feature = "json")]
     pub async fn json<T: for<'a> serde::Deserialize<'a>>(&mut self) -> Result<T, Error> {
         let str = self.str_contents().await?;
@@ -185,6 +210,8 @@ impl Body {
         Body(BodyInner::Incoming(Incoming { body, size_hint }))
     }
 
+    /// Construct a `Body` backed by a `futures_lite::Stream` impl. The stream
+    /// will be polled as the body is sent.
     pub fn from_stream<S>(stream: S) -> Self
     where
         S: futures_lite::Stream + Send + 'static,
@@ -196,17 +223,27 @@ impl Body {
         ))
     }
 
-    pub fn from_try_stream<S, D>(stream: S) -> Self
+    /// Construct a `Body` backed by a `futures_lite::Stream` impl. The stream
+    /// will be polled as the body is sent. If the stream gives an error, the
+    /// body will canceled, which closes the underlying connection.
+    pub fn from_try_stream<S, D, E>(stream: S) -> Self
     where
-        S: futures_lite::Stream<Item = Result<D, Error>> + Send + 'static,
+        S: futures_lite::Stream<Item = Result<D, E>> + Send + 'static,
         D: Into<Bytes>,
+        E: std::error::Error + Send + Sync + 'static,
     {
         use futures_lite::StreamExt;
         Self::from_http_body(http_body_util::StreamBody::new(
             stream.map(|bs| Ok::<_, Error>(Frame::data(bs?.into()))),
         ))
     }
 
+    /// Construct a `Body` backed by a `http_body::Body`. The http_body will
+    /// be polled as the body is sent. If the http_body poll gives an error,
+    /// the body will be canceled, which closes the underlying connection.
+    ///
+    /// Note, this is the only constructor which permits adding trailers to
+    /// the `Body`.
     pub fn from_http_body<B>(http_body: B) -> Self
     where
         B: HttpBody + Send + 'static,
@@ -259,9 +296,12 @@ impl From<String> for Body {
 
 impl From<crate::io::AsyncInputStream> for Body {
     fn from(r: crate::io::AsyncInputStream) -> Body {
-        // TODO: with another BodyInner variant for a boxed AsyncRead for which
-        // as_input_stream is_some, this could allow for use of
-        // crate::io::copy.
+        // TODO: this is skipping the wstd::io::copy optimization.
+        // in future, with another BodyInner variant for a boxed AsyncRead for
+        // which as_input_stream is_some, this could allow for use of
+        // crate::io::copy. But, we probably need to redesign AsyncRead to be
+        // a poll_read func in order to make it possible to use from
+        // http_body::Body::poll_frame.
         use futures_lite::stream::StreamExt;
         Body(BodyInner::Boxed(http_body_util::BodyExt::boxed_unsync(
             http_body_util::StreamBody::new(r.into_stream().map(|res| {
diff --git a/src/http/server.rs b/src/http/server.rs
@@ -8,7 +8,7 @@
 //! use wstd::http::{Request, Response, Body, Error};
 //! #[wstd::http_server]
 //! async fn main(_request: Request<Body>) -> Result<Response<Body>, Error> {
-//!     Ok(Response::new("Hello!\n".to_string().into()))
+//!     Ok(Response::new("Hello!\n".into()))
 //! }
 //! ```
 //!
@@ -26,6 +26,7 @@ use wasip2::http::types::OutgoingResponse;
 /// For use by the [`http_server`] macro only.
 ///
 /// [`http_server`]: crate::http_server
+#[doc(hidden)]
 #[must_use]
 pub struct Responder {
     outparam: ResponseOutparam,

Original file line number	Diff line number	Diff line change
`@@ -86,7 +86,7 @@ async fn main() -> Result<()> {`
`86`	`86`	`}`
`87`	`87`
`88`	`88`	`let body = if args.body {`
`89`		`- Body::from_input_stream(wstd::io::stdin().into_inner()).into_boxed_body()`
	`89`	`+ Body::from_try_stream(wstd::io::stdin().into_inner().into_stream()).into_boxed_body()`
`90`	`90`	`} else {`
`91`	`91`	`Body::empty().into_boxed_body()`
`92`	`92`	`};`