docs, example that doesnt use macro

pchickey · pchickey · commit d585681a14e6 · 2025-10-17T12:51:22.000-07:00
diff --git a/axum/examples/hello_world_nomacro.rs b/axum/examples/hello_world_nomacro.rs
@@ -0,0 +1,19 @@
+//! Run with
+//!
+//! ```sh
+//! cargo build -p wstd-axum --examples --target wasm32-wasip2
+//! wasmtime serve -Scli target/wasm32-wasip2/debug/examples/hello-world-nomacro.wasm
+//! ```
+
+use axum::{Router, response::Html, routing::get};
+use wstd::http::{Body, Error, Request, Response};
+
+#[wstd::http_server]
+async fn main(request: Request<Body>) -> Result<Response<Body>, Error> {
+    let service = Router::new().route("/", get(handler));
+    wstd_axum::serve(request, service).await
+}
+
+async fn handler() -> Html<&'static str> {
+    Html("<h1>Hello, World!</h1>")
+}
diff --git a/axum/src/lib.rs b/axum/src/lib.rs
@@ -1,3 +1,44 @@
+//! Support for the [`axum`] web server framework in wasi-http components, via
+//! [`wstd`].
+//!
+//! This crate is a pretty thin wrapper on [`wstd`] that allows users to
+//! use the [`axum`] crate on top of wstd's http support. This means that
+//! axum services can run anywhere the [wasi-http proxy world] is supported,
+//! e.g. in [`wasmtime serve`].
+//!
+//! Users of this crate should depend on `axum` with `default-features =
+//! false`, and opt in to any features that they require (e.g. form, json,
+//! matched-path, original-uri, query, tower-log, tracing). The axum crate
+//! features that require `hyper` or `tokio` are NOT supported (e.g. http1,
+//! http2, ws), because unlike in native applications, wasi-http components
+//! have an http implementation provided as imported interfaces (i.e.
+//! implemented the Wasm host), and do not use raw sockets inside of this
+//! program.
+//!
+//! # Examples
+//!
+//! The simplest use is via the `wstd_axum::http_server` proc macro.
+//! This macro can be applied to a sync or `async` `fn main` which returns
+//! an impl of the `tower_service::Service` trait, typically an
+//! `axum::Router`:
+//!
+//! ```rust,no_run
+#![doc = include_str!("../examples/hello_world.rs")]
+//! ```
+//!
+//! If users desire, they can instead use a `wstd::http_server` entry point
+//! and then use `wstd_axum::serve` directly. The following is equivelant
+//! to the above example:
+//!
+//! ```rust,no_run
+#![doc = include_str!("../examples/hello_world_nomacro.rs")]
+//! ```
+//!
+//! [`axum`]: https://docs.rs/axum/latest/axum/
+//! [`wstd`]: https://docs.rs/wstd/latest/wstd/
+//! [wasi-http proxy world]: https://github.com/WebAssembly/wasi-http
+//! [`wasmtime serve`]: https://wasmtime.dev/
+
 use axum::extract::Request;
 use axum::response::Response;
 use std::convert::Infallible;
diff --git a/test-programs/tests/axum_hello_world.rs b/test-programs/tests/axum_hello_world.rs
@@ -14,7 +14,18 @@ impl Drop for DontOrphan {
 }
 
 #[test_log::test]
-fn http_server() -> Result<()> {
+fn hello_world() -> Result<()> {
+    run(test_programs::axum::HELLO_WORLD)
+}
+
+#[test_log::test]
+fn hello_world_nomacro() -> Result<()> {
+    run(test_programs::axum::HELLO_WORLD_NOMACRO)
+}
+
+// The hello_world.rs and hello_world_nomacro.rs are identical in
+// functionality
+fn run(guest: &str) -> Result<()> {
     // Run wasmtime serve.
     // Enable -Scli because we currently don't have a way to build with the
     // proxy adapter, so we build with the default adapter.
@@ -23,7 +34,7 @@ fn http_server() -> Result<()> {
             .arg("serve")
             .arg("-Scli")
             .arg("--addr=127.0.0.1:8081")
-            .arg(test_programs::axum::HELLO_WORLD)
+            .arg(guest)
             .spawn()?,
     );
 
