Skip to content

Commit 3a8a58e

Browse files
juntaojuntao
committed
Update the HTTP services to the new SDKs
Signed-off-by: Michael Yuan <[email protected]>
1 parent d4660bc commit 3a8a58e

File tree

2 files changed

+64
-92
lines changed

2 files changed

+64
-92
lines changed

‎docs/develop/rust/http_service/client.md

+54-87
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,17 @@ WasmEdge allows Rust developers to use APIs they are already familiar with to ac
88

99
<!-- prettier-ignore -->
1010
:::note
11-
Before we start, ensure [you have Rust and WasmEdge installed](../setup.md). To make HTTPS requests, install the [WasmEdge TLS plug-in](../../../start/install.md#tls-plug-in).
11+
Before we start, ensure [you have Rust and WasmEdge installed](../setup.md).
1212
:::
1313

1414
We will discuss HTTP and HTTPS clients using popular Rust APIs.
1515

1616
- [The reqwest API](#the-reqwest-api)
1717
- [The hyper API](#the-hyper-api)
18-
- [The http_req API](#the-http_req-api)
1918

2019
## The reqwest API
2120

22-
The `reqwest` crate is a popular Rust library to create asynchronous HTTP clients. It is built on top of the `hyper` and `tokio` APIs. Many developers find it easier to use. But perhaps more importantly, many existing Rust applications use `reqwest`, and you can make them work in WasmEdge by simply replacing the `reqwest` crate with `reqwest_wasi`! Build and run [the example](https://github.com/WasmEdge/wasmedge_reqwest_demo/) in WasmEdge as follows.
21+
The `reqwest` crate is a popular Rust library to create asynchronous HTTP clients. It is built on top of the `hyper` and `tokio` APIs. Many developers find it easier to use. But perhaps more importantly, many existing Rust applications use `reqwest`, and you can make them work in WasmEdge by simply patching the `reqwest` crate in `Cargo.toml` with simple patches! Build and run [the example](https://github.com/WasmEdge/wasmedge_reqwest_demo/) in WasmEdge as follows.
2322

2423
<!-- prettier-ignore -->
2524
:::note
@@ -31,7 +30,7 @@ git clone https://github.com/WasmEdge/wasmedge_reqwest_demo
3130
cd wasmedge_reqwest_demo
3231

3332
# Build the Rust code
34-
cargo build --target wasm32-wasi --release
33+
RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release
3534
# Use the AoT compiler to get better performance
3635
wasmedge compile target/wasm32-wasi/release/http.wasm http.wasm
3736
wasmedge compile target/wasm32-wasi/release/https.wasm https.wasm
@@ -43,14 +42,25 @@ wasmedge http.wasm
4342
wasmedge https.wasm
4443
```
4544

46-
In your Rust application, import [the WasmEdge adapted reqwest crate](https://crates.io/crates/reqwest_wasi), which uses a special version of single-threaded Tokio that is adapted for WebAssembly. Just add the following lines to your `Cargo.toml`.
45+
In your Rust application, import the standard [reqwest](https://crates.io/crates/reqwest) and [tokio](https://crates.io/crates/tokio) crates. You will also patch a few dependency crates to make them aware of the WasmEdge socket API. Just add the following lines to your `Cargo.toml`.
4746

4847
```toml
48+
[patch.crates-io]
49+
tokio = { git = "https://github.com/second-state/wasi_tokio.git", branch = "v1.36.x" }
50+
socket2 = { git = "https://github.com/second-state/socket2.git", branch = "v0.5.x" }
51+
hyper = { git = "https://github.com/second-state/wasi_hyper.git", branch = "v0.14.x" }
52+
reqwest = { git = "https://github.com/second-state/wasi_reqwest.git", branch = "0.11.x" }
53+
4954
[dependencies]
50-
reqwest_wasi = { version = "0.11", features = ["json"] }
51-
tokio_wasi = { version = "1.21", features = ["full"] }
55+
reqwest = { version = "0.11", default-features = false, features = ["rustls-tls"] }
56+
tokio = { version = "1", features = ["rt", "macros", "net", "time"] }
5257
```
5358

59+
<!-- prettier-ignore -->
60+
:::note
61+
The `Cargo.toml` here shows that TLS is enabled. If you need to compile it on the MacOS, you will need the [wasi-sdk version of clang](../setup#compile-rust-tls-on-macos).
62+
:::
63+
5464
The [example Rust code](https://github.com/WasmEdge/wasmedge_reqwest_demo/blob/main/src/http.rs) below shows an HTTP GET request.
5565

5666
```rust
@@ -82,23 +92,6 @@ And here is an HTTP POST request.
8292
println!("POST: {}", body);
8393
```
8494

85-
### HTTPS support
86-
87-
In order to make HTTPS requests from `reqwest`, you will need to install WasmEdge with [the TLS plug-in](../../../start/install.md#tls-plug-in).
88-
89-
```bash
90-
curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- --plugins wasmedge_rustls
91-
```
92-
93-
Then, in `Cargo.toml`, you should enable the TLS feature.
94-
95-
```toml
96-
reqwest_wasi = { version = "0.11", features = ["wasmedge-tls"] }
97-
tokio_wasi = { version = "1", features = ["rt", "macros", "net", "time"] }
98-
```
99-
100-
Then, you can just replace the URLs in the above examples from `http` and `https`. [See details here](https://github.com/WasmEdge/wasmedge_reqwest_demo/blob/main/src/https.rs).
101-
10295
## The hyper API
10396

10497
The [hyper crate](https://crates.io/crates/hyper) is a widely used Rust library to create HTTP and HTTPS networking applications for both clients and servers. A key feature of the `hyper` crate is that it is based on the `tokio` runtime, which supports asynchronous network connections. Asynchronous HTTP or HTTPS requests do not block the execution of the calling application. It allows an application to make multiple concurrent HTTP requests and to process responses as they are received. That enables high-performance networking applications in WasmEdge. Build and run [the hyper example](https://github.com/WasmEdge/wasmedge_hyper_demo/) in WasmEdge as follows.
@@ -108,33 +101,64 @@ git clone https://github.com/WasmEdge/wasmedge_hyper_demo
108101
cd wasmedge_hyper_demo/client
109102

110103
# Build the Rust code
111-
cargo build --target wasm32-wasi --release
104+
RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release
112105
# Use the AoT compiler to get better performance
113106
wasmedge compile target/wasm32-wasi/release/wasmedge_hyper_client.wasm wasmedge_hyper_client.wasm
114107

115108
# Run the example
116109
wasmedge wasmedge_hyper_client.wasm
117110
```
118111

119-
The HTTPS version of the demo is as follows. Make sure that you install the [WasmEdge TLS plug-in](../../../start/install.md#tls-plug-in) first.
112+
In your Rust application, import the [hyper](https://crates.io/crates/hyper) crate,
113+
and patch it with WasmEdge sockets patches.
114+
Just add the following line to your `Cargo.toml`.
115+
116+
```toml
117+
[patch.crates-io]
118+
tokio = { git = "https://github.com/second-state/wasi_tokio.git", branch = "v1.36.x" }
119+
socket2 = { git = "https://github.com/second-state/socket2.git", branch = "v0.5.x" }
120+
hyper = { git = "https://github.com/second-state/wasi_hyper.git", branch = "v0.14.x" }
121+
122+
[dependencies]
123+
hyper = { version = "0.14", features = ["full"] }
124+
tokio = { version = "1", features = [ "rt", "macros", "net", "time", "io-util" ] }
125+
```
126+
127+
The HTTPS version of the demo is as follows.
120128

121129
```bash
122130
// Build
123131
cd wasmedge_hyper_demo/client-https
124-
cargo build --target wasm32-wasi --release
132+
RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release
125133
wasmedge compile target/wasm32-wasi/release/wasmedge_hyper_client_https.wasm wasmedge_hyper_client_https.wasm
126134

127135
// Run
128136
wasmedge wasmedge_hyper_client_https.wasm
129137
```
130138

131-
In your Rust application, import [the WasmEdge adapted hyper crate](https://crates.io/crates/hyper_wasi), which uses a special version of single-threaded Tokio that is adapted for WebAssembly. Just add the following line to your `Cargo.toml`.
139+
In the HTTPS version of `Cargo.toml`, you just need to import the standard [hyper-rustls](https://crates.io/crates/hyper-rustls), [rustls](https://crates.io/crates/rustls) and [webpki-roots](https://crates.io/crates/webpki-roots) crates with the same patches as above.
140+
141+
```
142+
[patch.crates-io]
143+
tokio = { git = "https://github.com/second-state/wasi_tokio.git", branch = "v1.36.x" }
144+
socket2 = { git = "https://github.com/second-state/socket2.git", branch = "v0.5.x" }
145+
hyper = { git = "https://github.com/second-state/wasi_hyper.git", branch = "v0.14.x" }
132146
133-
```toml
134147
[dependencies]
135-
hyper_wasi = "0.15.0"
148+
hyper = { version = "0.14", features = ["full"]}
149+
hyper-rustls = { version = "0.25", default-features = false, features = [ "http1", "tls12", "logging", "ring", "webpki-tokio" ] }
150+
rustls = { version = "0.22", default-features = false }
151+
webpki-roots = "0.26.1"
152+
153+
tokio = { version = "1", features = ["rt", "macros", "net", "time", "io-util"]}
154+
pretty_env_logger = "0.4.0"
136155
```
137156

157+
<!-- prettier-ignore -->
158+
:::note
159+
If you need to compile `rustls` as shown in the `Cargo.toml` above on the MacOS, you will need the [wasi-sdk version of clang](../setup#compile-rust-tls-on-macos).
160+
:::
161+
138162
The [Rust example code](https://github.com/WasmEdge/wasmedge_hyper_demo/blob/main/client/src/main.rs) below shows an HTTP GET request.
139163

140164
```rust
@@ -188,60 +212,3 @@ async fn post_url_return_str (url: hyper::Uri, post_body: &'static [u8]) -> Resu
188212
}
189213
```
190214

191-
## The http_req API
192-
193-
If your WasmEdge application only needs to make sequential requests to external web services, a synchronous client is easier to work with. It allows you to make a request, wait for the response, and move on once the response is fully received. Use the `http_req` API to make simple synchronous HTTP requests. Build and run [the example](https://github.com/second-state/http_req/) in WasmEdge.
194-
195-
```bash
196-
git clone https://github.com/second-state/http_req
197-
cd http_req/
198-
199-
# Build the Rust Code
200-
cargo build --target wasm32-wasi --release
201-
# Use the AoT compiler to get better performance
202-
wasmedge compile target/wasm32-wasi/release/get.wasm get.wasm
203-
204-
# Run the example
205-
wasmedge get.wasm
206-
... ...
207-
wasmedge get_https.wasm
208-
... ...
209-
```
210-
211-
In your Rust application, import the [http_req_wasi](https://crates.io/crates/http_req_wasi) crate, which is compatible with [http_req](https://github.com/jayjamesjay/http_req) at the API level. Just add the following line to your `Cargo.toml`.
212-
213-
```toml
214-
[dependencies]
215-
http_req_wasi = "0.10"
216-
```
217-
218-
The example below shows an [HTTP GET request](https://github.com/second-state/http_req/blob/master/examples/get.rs). For HTTPS requests, you can [simply change](https://github.com/second-state/http_req/blob/master/examples/get_https.rs) the `http` URL to `https`.
219-
220-
```rust
221-
use http_req::request;
222-
223-
fn main() {
224-
let mut writer = Vec::new(); //container for body of a response
225-
let res = request::get("http://eu.httpbin.org/get?msg=WasmEdge", &mut writer).unwrap();
226-
227-
println!("Status: {} {}", res.status_code(), res.reason());
228-
println!("Headers {}", res.headers());
229-
println!("{}", String::from_utf8_lossy(&writer));
230-
}
231-
```
232-
233-
And here is an [HTTP POST request](https://github.com/second-state/http_req/blob/master/examples/post.rs). For HTTPS requests, you can [simply change](https://github.com/second-state/http_req/blob/master/examples/post_https.rs) the `http` URL to `https`.
234-
235-
```rust
236-
use http_req::request;
237-
238-
fn main() {
239-
let mut writer = Vec::new(); //container for body of a response
240-
const BODY: &[u8; 27] = b"field1=value1&field2=value2";
241-
let res = request::post("http://eu.httpbin.org/post", BODY, &mut writer).unwrap();
242-
243-
println!("Status: {} {}", res.status_code(), res.reason());
244-
println!("Headers {}", res.headers());
245-
println!("{}", String::from_utf8_lossy(&writer));
246-
}
247-
```

‎docs/develop/rust/http_service/server.md

+10-5
Original file line numberDiff line numberDiff line change
@@ -71,14 +71,14 @@ async fn main() {
7171

7272
## The hyper API
7373

74-
The `warp` crate is convenient to use. But oftentimes, developers need access to lower-level APIs. The `hyper` crate is an excellent HTTP library for that. Build and run [the example](https://github.com/WasmEdge/wasmedge_hyper_demo/blob/main/server/) in WasmEdge as follows.
74+
The `hyper` crate is an excellent library for building HTTP servers using customizable low level APIs. Build and run [the example](https://github.com/WasmEdge/wasmedge_hyper_demo/blob/main/server/) in WasmEdge as follows.
7575

7676
```bash
7777
git clone https://github.com/WasmEdge/wasmedge_hyper_demo
7878
cd wasmedge_hyper_demo/server
7979

8080
# Build the Rust code
81-
cargo build --target wasm32-wasi --release
81+
RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release
8282
# Use the AoT compiler to get better performance
8383
wasmedge compile target/wasm32-wasi/release/wasmedge_hyper_server.wasm wasmedge_hyper_server.wasm
8484

@@ -93,12 +93,17 @@ $ curl http://localhost:8080/echo -X POST -d "WasmEdge"
9393
WasmEdge
9494
```
9595

96-
In your Rust application, import the WasmEdge adapted `hyper_wasi` crate, which uses a special version of single threaded Tokio that is adapted for WebAssembly. Just add the following lines to your `Cargo.toml`.
96+
In your Rust application, import the [hyper](https://crates.io/crates/hyper) and [tokio](https://crates.io/crates/tokio) crates, as well as the WasmEdge patches. Just add the following lines to your `Cargo.toml`.
9797

9898
```toml
99+
[patch.crates-io]
100+
tokio = { git = "https://github.com/second-state/wasi_tokio.git", branch = "v1.36.x" }
101+
socket2 = { git = "https://github.com/second-state/socket2.git", branch = "v0.5.x" }
102+
hyper = { git = "https://github.com/second-state/wasi_hyper.git", branch = "v0.14.x" }
103+
99104
[dependencies]
100-
tokio_wasi = { version = "1", features = ["rt", "macros", "net", "time", "io-util"]}
101-
hyper_wasi = "0.15.0"
105+
hyper = { version = "0.14", features = ["full"]}
106+
tokio = { version = "1", features = ["rt", "macros", "net", "time", "io-util"]}
102107
```
103108

104109
The [Rust example code](https://github.com/WasmEdge/wasmedge_hyper_demo/blob/main/server/src/main.rs) below shows an HTTP server that echoes back any incoming request.

0 commit comments

Comments
 (0)