Documentation

kflansburg · kflansburg · commit df81eb1492cf · 2024-03-13T14:45:49.000-04:00
diff --git a/README.md b/README.md
@@ -38,6 +38,43 @@ pub async fn main(req: Request, env: Env, _ctx: worker::Context) -> Result<Respo
 }
 ```
 
+### `http` Feature
+
+`worker` `0.1` introduced an `http` feature which starts to replace custom types with widely used types from the [`http`](https://docs.rs/http/latest/http/) crate.
+
+This makes it much easier to use crates which use these standard types such as `axum` and `hyper`. 
+
+This currently does a few things:
+
+1. Introduce `Body`, which implements `http_body::Body` and is a simple wrapper around `web_sys::ReadableStream`. 
+1. The `req` argument when using the `[event(fetch)]` macro becomes `http::Request<worker::Body>`.
+1. The expected return type for the fetch handler is `http::Response<B>` where `B` can be any `http_body::Body`.
+1. The argument for `Fetcher::fetch_request` is `http::Request<worker::Body>`. 
+1. The return type of `Fetcher::fetch_request` is `http::Response<worker::Body>`.
+
+The end result is being able to use frameworks like `axum` directly (see [example](./examples/axum)): 
+
+```rust
+pub async fn root() -> &'static str {
+    "Hello Axum!"
+}
+
+fn router() -> Router {
+    Router::new().route("/", get(root))
+}
+
+#[event(fetch)]
+async fn fetch(
+    req: HttpRequest,
+    _env: Env,
+    _ctx: Context,
+) -> Result<axum::http::Response<axum::body::Body>> {
+    Ok(router().call(req).await?)
+}
+```
+
+We also implement `From::from` between `worker::Request` and `http::Request<worker::Body>`, and between `worker::Response` and `http::Response<worker::Body>`. This allows you to convert your code incrementally if it is tightly coupled to the original types.
+
 ### Or use the `Router`:
 
 Parameterize routes and access the parameter values from within a handler. Each handler function takes a
diff --git a/worker/src/http/body.rs b/worker/src/http/body.rs
@@ -35,7 +35,7 @@ impl Body {
         Self(None)
     }
 
-    /// Create a `Body` using a [`Stream`](futures::stream::Stream)
+    /// Create a `Body` using a [`Stream`](futures_util::stream::Stream)
     pub fn from_stream<S>(stream: S) -> Result<Self, crate::Error>
     where
         S: TryStream + 'static,
diff --git a/worker/src/http/request.rs b/worker/src/http/request.rs
@@ -16,6 +16,8 @@ fn version_from_string(version: &str) -> http::Version {
     }
 }
 
+/// **Requires** `http` feature. Convert [`web_sys::Request`](web_sys::Request)
+/// to [`worker::HttpRequest`](worker::HttpRequest)
 pub fn from_wasm(req: web_sys::Request) -> http::Request<Body> {
     let mut builder = http::request::Builder::new()
         .uri(req.url())
@@ -38,6 +40,8 @@ pub fn from_wasm(req: web_sys::Request) -> http::Request<Body> {
     }
 }
 
+/// **Requires** `http` feature. Convert [`worker::HttpRequest`](worker::HttpRequest)
+/// to [`web_sys::Request`](web_sys::Request)
 pub fn to_wasm(mut req: http::Request<Body>) -> web_sys::Request {
     let mut init = web_sys::RequestInit::new();
     init.method(req.method().as_str());
diff --git a/worker/src/http/response.rs b/worker/src/http/response.rs
@@ -58,6 +58,8 @@ impl<B: http_body::Body<Data = Bytes>> Stream for BodyStream<B> {
     }
 }
 
+/// **Requires** `http` feature. Convert generic [`http::Response<B>`](worker::HttpResponse)
+/// to [`web_sys::Resopnse`](web_sys::Response) where `B` can be any [`http_body::Body`](http_body::Body)
 pub fn to_wasm<B>(mut res: http::Response<B>) -> web_sys::Response
 where
     B: http_body::Body<Data = Bytes> + 'static,
@@ -85,6 +87,8 @@ where
         .unwrap()
 }
 
+/// **Requires** `http` feature. Convert [`web_sys::Resopnse`](web_sys::Response)
+/// to [`worker::HttpResponse`](worker::HttpResponse)
 pub fn from_wasm(res: web_sys::Response) -> HttpResponse {
     let mut builder =
         http::response::Builder::new().status(http::StatusCode::from_u16(res.status()).unwrap());
diff --git a/worker/src/lib.rs b/worker/src/lib.rs
@@ -84,13 +84,17 @@ mod websocket;
 pub type Result<T> = StdResult<T, error::Error>;
 
 #[cfg(feature = "http")]
+/// **Requires** `http` feature. A convenience Body type which wraps [`web_sys::ReadableStream`](web_sys::ReadableStream)
+/// and implements [`http_body::Body`](http_body::Body)
 pub use http::body::Body;
 #[cfg(feature = "http")]
 pub use http::{
     request::from_wasm as request_from_wasm, request::to_wasm as request_to_wasm,
     response::from_wasm as response_from_wasm, response::to_wasm as response_to_wasm,
 };
 #[cfg(feature = "http")]
+/// **Requires** `http` feature. Type alias for `http::Request<worker::Body>`.
 pub type HttpRequest = ::http::Request<http::body::Body>;
 #[cfg(feature = "http")]
+/// **Requires** `http` feature. Type alias for `http::Response<worker::Body>`.
 pub type HttpResponse = ::http::Response<http::body::Body>;

Original file line number	Diff line number	Diff line change
`@@ -35,7 +35,7 @@ impl Body {`
`35`	`35`	`Self(None)`
`36`	`36`	`}`
`37`	`37`
`38`		- /// Create a `Body` using a [`Stream`](futures::stream::Stream)
	`38`	+ /// Create a `Body` using a [`Stream`](futures_util::stream::Stream)
`39`	`39`	`pub fn from_stream<S>(stream: S) -> Result<Self, crate::Error>`
`40`	`40`	`where`
`41`	`41`	`S: TryStream + 'static,`
Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,8 @@ fn version_from_string(version: &str) -> http::Version {`
`16`	`16`	`}`
`17`	`17`	`}`
`18`	`18`
	`19`	+/// Requires `http` feature. Convert [`web_sys::Request`](web_sys::Request)
	`20`	+/// to [`worker::HttpRequest`](worker::HttpRequest)
`19`	`21`	`pub fn from_wasm(req: web_sys::Request) -> http::Request<Body> {`
`20`	`22`	`let mut builder = http::request::Builder::new()`
`21`	`23`	`.uri(req.url())`
`@@ -38,6 +40,8 @@ pub fn from_wasm(req: web_sys::Request) -> http::Request<Body> {`
`38`	`40`	`}`
`39`	`41`	`}`
`40`	`42`
	`43`	+/// Requires `http` feature. Convert [`worker::HttpRequest`](worker::HttpRequest)
	`44`	+/// to [`web_sys::Request`](web_sys::Request)
`41`	`45`	`pub fn to_wasm(mut req: http::Request<Body>) -> web_sys::Request {`
`42`	`46`	`let mut init = web_sys::RequestInit::new();`
`43`	`47`	`init.method(req.method().as_str());`
Original file line number	Diff line number	Diff line change
`@@ -58,6 +58,8 @@ impl<B: http_body::Body<Data = Bytes>> Stream for BodyStream<B> {`
`58`	`58`	`}`
`59`	`59`	`}`
`60`	`60`
	`61`	+/// Requires `http` feature. Convert generic [`http::Response<B>`](worker::HttpResponse)
	`62`	+/// to [`web_sys::Resopnse`](web_sys::Response) where `B` can be any [`http_body::Body`](http_body::Body)
`61`	`63`	`pub fn to_wasm<B>(mut res: http::Response<B>) -> web_sys::Response`
`62`	`64`	`where`
`63`	`65`	`B: http_body::Body<Data = Bytes> + 'static,`
`@@ -85,6 +87,8 @@ where`
`85`	`87`	`.unwrap()`
`86`	`88`	`}`
`87`	`89`
	`90`	+/// Requires `http` feature. Convert [`web_sys::Resopnse`](web_sys::Response)
	`91`	+/// to [`worker::HttpResponse`](worker::HttpResponse)
`88`	`92`	`pub fn from_wasm(res: web_sys::Response) -> HttpResponse {`
`89`	`93`	`let mut builder =`
`90`	`94`	`http::response::Builder::new().status(http::StatusCode::from_u16(res.status()).unwrap());`