Skip to content

add wstd-axum crate #97

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 11 commits into from
Oct 23, 2025
Merged

add wstd-axum crate #97

merged 11 commits into from
Oct 23, 2025

Conversation

@pchickey
Copy link
Contributor

@pchickey pchickey commented Oct 17, 2025 •
edited
Loading

Based on #92

wstd-axum is a crate which makes it trivial to use the axum crate with a wasip2 http server.

It contains async fn serve(request: Request<Body>, service: impl tower_http::Service) -> Result<Response<Body>> which is the analog for axum::serve, except in wasi-http terms instead of using a tokio socket.

It also exports the wstd_axum::http_server proc macro which gets rid of the boilerplate used to convert a wstd::http_server to an axum server, and makes it so you never even see the wstd::http types in the resulting program.

use axum::{Router, response::Html, routing::get};

#[wstd_axum::http_server]
fn main() -> Router {
    // build our application with a route
    Router::new().route("/", get(handler))
}

async fn handler() -> Html<&'static str> {
    Html("<h1>Hello, World!</h1>")
}

The integration itself is very thin, because http_body::Body is doing 99% of the work!

This is added as a separate crate, rather than an optional feature on wstd, because:

  1. we might want to make separate point releases for just wstd-axum that just bump the axum dependency version
  2. axum integration feels more "opinionated" than just http_body::Body integration. It would be perfectly fine to integrate other http server frameworks with wstd! Axum was just the one I've seen the most desire for, from the users I personally have informally surveyed.
  3. the wstd_axum::http_server macro changes up the signature of main enough that it seems like a separate sort of thing. Idk, its vibes, I can go either way.

In the future, I expect to refactor the macro to better support instance reuse, by initializing the Service into a OnceLock on first request and cloning it on subsequent, and making it possible to pre-initialize via component-init aka wizer.

Weather example

To show Axum working in a nontrivial application and wstd::http::Client, I added the example axum/examples/weather.rs which implements a toy weather http service by making calls to free geocoding and weather APIs run by open-meteo.com.

This example is derived from a standalone demo I wrote for an earlier wstd at https://github.com/pchickey/wasi-http-demos, and I'll probably upstream it back to there after we get releases out.

Test refactoring

Incidentally, as part of this PR, I cleaned up some mess around testing.

Previously, there was a test-programs crate which existed to have bins which include! the sources of some of the examples in the wstd crate. The test-programs-artifacts crate existed to build test-programs with --target wasm32-wasip2 with its build.rs and enumerate the binaries as str constants exported by the lib, and then write native integration tests that run those in wasmtime and hit wasmtime with the appropriate external stimulus (http requests or tcp sockets).

There was no need to have the intermediate test-programs crate. The test-programs-artifacts can just build and use the wstd examples directly. When adding the wstd-axum crate's examples, I noticed this was totally unnecessary, and I can't figure out why I did it historically. So, test-programs got erased and test-programs-artifacts became test-programs.

In a future PR, I will need to add tests that exercise the other wstd examples (http_client, complex_http_client).

Edition 2024 upgrade

The workspace has been upgraded to 2024 edition, because I just noticed it was not yet upgraded. This really could have been separated out into another PR that would require a rubber stamp, so I folded it in. Its almost entirely rustfmt order changes, and some rules around match and ref mut changed in a trivial manner. These changes are separated out into their own commit.

@pchickey pchickey requested a review from yoshuawuyts October 17, 2025 17:54
@pchickey pchickey changed the title add wstd_axum crate add wstd-axum crate Oct 17, 2025
@pchickey pchickey changed the base branch from main to pch/server_result_body October 17, 2025 18:19
@pchickey pchickey force-pushed the pch/wstd_axum branch 3 times, most recently from d585681 to b6250e6 Compare October 20, 2025 22:51
Base automatically changed from pch/server_result_body to main October 23, 2025 17:48
yoshuawuyts
yoshuawuyts approved these changes Oct 23, 2025
View reviewed changes
Copy link
Member

@yoshuawuyts yoshuawuyts left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reviewed this in a call today; looks great!

@pchickey pchickey merged commit 3dc9f05 into main Oct 23, 2025
5 checks passed
@pchickey pchickey deleted the pch/wstd_axum branch October 23, 2025 18:04
@pchickey pchickey mentioned this pull request Oct 23, 2025
Merged
@MendyBerger MendyBerger mentioned this pull request Nov 27, 2025
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@yoshuawuyts yoshuawuyts yoshuawuyts approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@pchickey @yoshuawuyts