From 743be712db1784a1b580348cddf7a94be32618e3 Mon Sep 17 00:00:00 2001 From: Michael Yuan Date: Mon, 27 May 2024 11:25:36 -0500 Subject: [PATCH] Remove TLS from install guide (#229) * Remove TLS from install guide Signed-off-by: Michael Yuan * Add TLS plug-in as a deprecated feature Signed-off-by: Michael Yuan * Add new socket API docs Signed-off-by: Michael Yuan * Update the HTTP services to the new SDKs Signed-off-by: Michael Yuan --------- Signed-off-by: Michael Yuan --- docs/develop/rust/database/my_sql_driver.md | 194 ++++++++++++++++++-- docs/develop/rust/http_service/client.md | 141 ++++++-------- docs/develop/rust/http_service/server.md | 15 +- docs/develop/rust/setup.md | 38 +++- docs/start/install.md | 54 +++++- 5 files changed, 328 insertions(+), 114 deletions(-) diff --git a/docs/develop/rust/database/my_sql_driver.md b/docs/develop/rust/database/my_sql_driver.md index ea9c7abc..80033cff 100644 --- a/docs/develop/rust/database/my_sql_driver.md +++ b/docs/develop/rust/database/my_sql_driver.md @@ -8,7 +8,7 @@ The database connection is necessary for today's enterprise development. WasmEdg :::note -Before we start, ensure [you have Rust and WasmEdge installed](../setup.md). If you are connecting to a remote MySQL database using TLS, you will need to [install the TLS plugin](../../../start/install.md#tls-plug-in) for WasmEdge as well. +Before we start, ensure [you have Rust and WasmEdge installed](../setup.md). ::: ## Run the example @@ -20,18 +20,13 @@ git clone https://github.com/WasmEdge/wasmedge-db-examples cd wasmedge-db-examples/mysql_async # Compile the rust code into WASM -cargo build --target wasm32-wasi --release +RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release # Execute MySQL statements against a MySQL database at mysql://user:passwd@127.0.0.1:3306 wasmedge --env "DATABASE_URL=mysql://user:passwd@127.0.0.1:3306/mysql" target/wasm32-wasi/release/crud.wasm ``` -To use TLS, you will need to turn on the `default-rustls` feature in `Cargo.toml`. - -```toml -mysql_async_wasi = { version = "0.31", features = [ "default-rustls" ] } -``` - +To use TLS, you will need to turn on the `default-rustls` feature on the `mysql_async` crate in `Cargo.toml`. Then, run the application as follows. ```toml @@ -39,9 +34,182 @@ Then, run the application as follows. wasmedge --env "DATABASE_SSL=1" --env "DATABASE_URL=mysql://user:passwd@mydb.123456789012.us-east-1.rds.amazonaws.com:3306/mysql" crud.wasm ``` -## Code explanation +## Configuration + +In order to compile the `mysql_async` and `tokio` crates, we will need to apply two patches to add +WasmEdge-specific socket APIs to those crates. The following example shows that the TLS connection is enabled. + +``` +[patch.crates-io] +tokio = { git = "https://github.com/second-state/wasi_tokio.git", branch = "v1.36.x" } +socket2 = { git = "https://github.com/second-state/socket2.git", branch = "v0.5.x" } + +[dependencies] +mysql_async = { version = "0.34", default-features=false, features = [ "default-rustls" ], git="https://github.com/blackbeam/mysql_async.git" } +zstd-sys = "=2.0.9" +tokio = { version = "1", features = [ "io-util", "fs", "net", "time", "rt", "macros"] } +``` + +## Code example + +The following code shows how to connect to a MySQL database server, and then insert, update, and delete records using SQL +statements. + +Connect to a MySQL database. + +``` + // Below we create a customized connection pool + let opts = Opts::from_url(&*get_url()).unwrap(); + let mut builder = OptsBuilder::from_opts(opts); + if std::env::var("DATABASE_SSL").is_ok() { + builder = builder.ssl_opts(SslOpts::default()); + } + // The connection pool will have a min of 5 and max of 10 connections. + let constraints = PoolConstraints::new(5, 10).unwrap(); + let pool_opts = PoolOpts::default().with_constraints(constraints); + + let pool = Pool::new(builder.pool_opts(pool_opts)); + let mut conn = pool.get_conn().await.unwrap(); +``` + +Create a table on the connected database. + +``` + // create table if no tables exist + let result = r"SHOW TABLES LIKE 'orders';" + .with(()) + .map(&mut conn, |s: String| String::from(s)) + .await?; + + if result.len() == 0 { + // table doesn't exist, create a new one + r"CREATE TABLE orders (order_id INT, production_id INT, quantity INT, amount FLOAT, shipping FLOAT, tax FLOAT, shipping_address VARCHAR(20));".ignore(&mut conn).await?; + println!("create new table"); + } else { + // delete all data from the table. + println!("delete all from orders"); + r"DELETE FROM orders;".ignore(&mut conn).await?; + } +``` + +Insert some records into the MySQL database using SQL. + +``` + let orders = vec![ + Order::new(1, 12, 2, 56.0, 15.0, 2.0, String::from("Mataderos 2312")), + Order::new(2, 15, 3, 256.0, 30.0, 16.0, String::from("1234 NW Bobcat")), + Order::new(3, 11, 5, 536.0, 50.0, 24.0, String::from("20 Havelock")), + Order::new(4, 8, 8, 126.0, 20.0, 12.0, String::from("224 Pandan Loop")), + Order::new(5, 24, 1, 46.0, 10.0, 2.0, String::from("No.10 Jalan Besar")), + ]; + + r"INSERT INTO orders (order_id, production_id, quantity, amount, shipping, tax, shipping_address) + VALUES (:order_id, :production_id, :quantity, :amount, :shipping, :tax, :shipping_address)" + .with(orders.iter().map(|order| { + params! { + "order_id" => order.order_id, + "production_id" => order.production_id, + "quantity" => order.quantity, + "amount" => order.amount, + "shipping" => order.shipping, + "tax" => order.tax, + "shipping_address" => &order.shipping_address, + } + })) + .batch(&mut conn) + .await?; +``` + +Query the database. + +``` + // query data + let loaded_orders = "SELECT * FROM orders" + .with(()) + .map( + &mut conn, + |(order_id, production_id, quantity, amount, shipping, tax, shipping_address)| { + Order::new( + order_id, + production_id, + quantity, + amount, + shipping, + tax, + shipping_address, + ) + }, + ) + .await?; + dbg!(loaded_orders.len()); + dbg!(loaded_orders); +``` + +Delete some records from the database. + +``` + // // delete some data + r"DELETE FROM orders WHERE order_id=4;" + .ignore(&mut conn) + .await?; + + // query data + let loaded_orders = "SELECT * FROM orders" + .with(()) + .map( + &mut conn, + |(order_id, production_id, quantity, amount, shipping, tax, shipping_address)| { + Order::new( + order_id, + production_id, + quantity, + amount, + shipping, + tax, + shipping_address, + ) + }, + ) + .await?; + dbg!(loaded_orders.len()); + dbg!(loaded_orders); +``` + +Update records in the MySQL database. + +``` + // // update some data + r"UPDATE orders + SET shipping_address = '8366 Elizabeth St.' + WHERE order_id = 2;" + .ignore(&mut conn) + .await?; + // query data + let loaded_orders = "SELECT * FROM orders" + .with(()) + .map( + &mut conn, + |(order_id, production_id, quantity, amount, shipping, tax, shipping_address)| { + Order::new( + order_id, + production_id, + quantity, + amount, + shipping, + tax, + shipping_address, + ) + }, + ) + .await?; + dbg!(loaded_orders.len()); + dbg!(loaded_orders); +``` + +Close the database connection. + +``` + drop(conn); + pool.disconnect().await.unwrap(); +``` - -:::info -Work in Progress -::: diff --git a/docs/develop/rust/http_service/client.md b/docs/develop/rust/http_service/client.md index 868bcd01..3c364c6c 100644 --- a/docs/develop/rust/http_service/client.md +++ b/docs/develop/rust/http_service/client.md @@ -8,18 +8,17 @@ WasmEdge allows Rust developers to use APIs they are already familiar with to ac :::note -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). +Before we start, ensure [you have Rust and WasmEdge installed](../setup.md). ::: We will discuss HTTP and HTTPS clients using popular Rust APIs. - [The reqwest API](#the-reqwest-api) - [The hyper API](#the-hyper-api) -- [The http_req API](#the-http_req-api) ## The reqwest API -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. +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. :::note @@ -31,7 +30,7 @@ git clone https://github.com/WasmEdge/wasmedge_reqwest_demo cd wasmedge_reqwest_demo # Build the Rust code -cargo build --target wasm32-wasi --release +RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release # Use the AoT compiler to get better performance wasmedge compile target/wasm32-wasi/release/http.wasm http.wasm wasmedge compile target/wasm32-wasi/release/https.wasm https.wasm @@ -43,14 +42,25 @@ wasmedge http.wasm wasmedge https.wasm ``` -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`. +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`. ```toml +[patch.crates-io] +tokio = { git = "https://github.com/second-state/wasi_tokio.git", branch = "v1.36.x" } +socket2 = { git = "https://github.com/second-state/socket2.git", branch = "v0.5.x" } +hyper = { git = "https://github.com/second-state/wasi_hyper.git", branch = "v0.14.x" } +reqwest = { git = "https://github.com/second-state/wasi_reqwest.git", branch = "0.11.x" } + [dependencies] -reqwest_wasi = { version = "0.11", features = ["json"] } -tokio_wasi = { version = "1.21", features = ["full"] } +reqwest = { version = "0.11", default-features = false, features = ["rustls-tls"] } +tokio = { version = "1", features = ["rt", "macros", "net", "time"] } ``` + +:::note +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). +::: + The [example Rust code](https://github.com/WasmEdge/wasmedge_reqwest_demo/blob/main/src/http.rs) below shows an HTTP GET request. ```rust @@ -82,23 +92,6 @@ And here is an HTTP POST request. println!("POST: {}", body); ``` -### HTTPS support - -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). - -```bash -curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- --plugins wasmedge_rustls -``` - -Then, in `Cargo.toml`, you should enable the TLS feature. - -```toml -reqwest_wasi = { version = "0.11", features = ["wasmedge-tls"] } -tokio_wasi = { version = "1", features = ["rt", "macros", "net", "time"] } -``` - -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). - ## The hyper API 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,7 +101,7 @@ git clone https://github.com/WasmEdge/wasmedge_hyper_demo cd wasmedge_hyper_demo/client # Build the Rust code -cargo build --target wasm32-wasi --release +RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release # Use the AoT compiler to get better performance wasmedge compile target/wasm32-wasi/release/wasmedge_hyper_client.wasm wasmedge_hyper_client.wasm @@ -116,25 +109,56 @@ wasmedge compile target/wasm32-wasi/release/wasmedge_hyper_client.wasm wasmedge_ wasmedge wasmedge_hyper_client.wasm ``` -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. +In your Rust application, import the [hyper](https://crates.io/crates/hyper) crate, +and patch it with WasmEdge sockets patches. +Just add the following line to your `Cargo.toml`. + +```toml +[patch.crates-io] +tokio = { git = "https://github.com/second-state/wasi_tokio.git", branch = "v1.36.x" } +socket2 = { git = "https://github.com/second-state/socket2.git", branch = "v0.5.x" } +hyper = { git = "https://github.com/second-state/wasi_hyper.git", branch = "v0.14.x" } + +[dependencies] +hyper = { version = "0.14", features = ["full"] } +tokio = { version = "1", features = [ "rt", "macros", "net", "time", "io-util" ] } +``` + +The HTTPS version of the demo is as follows. ```bash // Build cd wasmedge_hyper_demo/client-https -cargo build --target wasm32-wasi --release +RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release wasmedge compile target/wasm32-wasi/release/wasmedge_hyper_client_https.wasm wasmedge_hyper_client_https.wasm // Run wasmedge wasmedge_hyper_client_https.wasm ``` -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`. +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. + +``` +[patch.crates-io] +tokio = { git = "https://github.com/second-state/wasi_tokio.git", branch = "v1.36.x" } +socket2 = { git = "https://github.com/second-state/socket2.git", branch = "v0.5.x" } +hyper = { git = "https://github.com/second-state/wasi_hyper.git", branch = "v0.14.x" } -```toml [dependencies] -hyper_wasi = "0.15.0" +hyper = { version = "0.14", features = ["full"]} +hyper-rustls = { version = "0.25", default-features = false, features = [ "http1", "tls12", "logging", "ring", "webpki-tokio" ] } +rustls = { version = "0.22", default-features = false } +webpki-roots = "0.26.1" + +tokio = { version = "1", features = ["rt", "macros", "net", "time", "io-util"]} +pretty_env_logger = "0.4.0" ``` + +:::note +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). +::: + The [Rust example code](https://github.com/WasmEdge/wasmedge_hyper_demo/blob/main/client/src/main.rs) below shows an HTTP GET request. ```rust @@ -188,60 +212,3 @@ async fn post_url_return_str (url: hyper::Uri, post_body: &'static [u8]) -> Resu } ``` -## The http_req API - -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. - -```bash -git clone https://github.com/second-state/http_req -cd http_req/ - -# Build the Rust Code -cargo build --target wasm32-wasi --release -# Use the AoT compiler to get better performance -wasmedge compile target/wasm32-wasi/release/get.wasm get.wasm - -# Run the example -wasmedge get.wasm -... ... -wasmedge get_https.wasm -... ... -``` - -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`. - -```toml -[dependencies] -http_req_wasi = "0.10" -``` - -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`. - -```rust -use http_req::request; - -fn main() { - let mut writer = Vec::new(); //container for body of a response - let res = request::get("http://eu.httpbin.org/get?msg=WasmEdge", &mut writer).unwrap(); - - println!("Status: {} {}", res.status_code(), res.reason()); - println!("Headers {}", res.headers()); - println!("{}", String::from_utf8_lossy(&writer)); -} -``` - -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`. - -```rust -use http_req::request; - -fn main() { - let mut writer = Vec::new(); //container for body of a response - const BODY: &[u8; 27] = b"field1=value1&field2=value2"; - let res = request::post("http://eu.httpbin.org/post", BODY, &mut writer).unwrap(); - - println!("Status: {} {}", res.status_code(), res.reason()); - println!("Headers {}", res.headers()); - println!("{}", String::from_utf8_lossy(&writer)); -} -``` diff --git a/docs/develop/rust/http_service/server.md b/docs/develop/rust/http_service/server.md index 8ec06db7..c705ffe8 100644 --- a/docs/develop/rust/http_service/server.md +++ b/docs/develop/rust/http_service/server.md @@ -71,14 +71,14 @@ async fn main() { ## The hyper API -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. +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. ```bash git clone https://github.com/WasmEdge/wasmedge_hyper_demo cd wasmedge_hyper_demo/server # Build the Rust code -cargo build --target wasm32-wasi --release +RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release # Use the AoT compiler to get better performance wasmedge compile target/wasm32-wasi/release/wasmedge_hyper_server.wasm wasmedge_hyper_server.wasm @@ -93,12 +93,17 @@ $ curl http://localhost:8080/echo -X POST -d "WasmEdge" WasmEdge ``` -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`. +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`. ```toml +[patch.crates-io] +tokio = { git = "https://github.com/second-state/wasi_tokio.git", branch = "v1.36.x" } +socket2 = { git = "https://github.com/second-state/socket2.git", branch = "v0.5.x" } +hyper = { git = "https://github.com/second-state/wasi_hyper.git", branch = "v0.14.x" } + [dependencies] -tokio_wasi = { version = "1", features = ["rt", "macros", "net", "time", "io-util"]} -hyper_wasi = "0.15.0" +hyper = { version = "0.14", features = ["full"]} +tokio = { version = "1", features = ["rt", "macros", "net", "time", "io-util"]} ``` 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. diff --git a/docs/develop/rust/setup.md b/docs/develop/rust/setup.md index d40bb0bd..84e5b416 100644 --- a/docs/develop/rust/setup.md +++ b/docs/develop/rust/setup.md @@ -32,4 +32,40 @@ To build a WASM file running in server-side WebAssembly like WasmEdge, we need t rustup target add wasm32-wasi ``` -That's it. Go to the following chapters to build and compile Rust programs in action. +## Special notes + +### Async networking with tokio + +WasmEdge supports async networking APIs provided by [Tokio](https://tokio.rs/) and related crates. If you have tokio in your `Cargo.toml`, you +need to add a few config flags to help the Rust compiler choose the correct feature branches in the library source code. Here is an example of `cargo build` command for +compiling a tokio app to Wasm. + +``` +RUSTFLAGS="--cfg wasmedge --cfg tokio_unstable" cargo build --target wasm32-wasi --release +``` + +Alternatively, you could add these lines to the `.cargo/config.toml` file. + +``` +[build] +target = "wasm32-wasi" +rustflags = ["--cfg", "wasmedge", "--cfg", "tokio_unstable"] +``` + +### Compile Rust TLS on MacOS + +The standard `cargo` toolchain can support the [Rust TLS](https://github.com/rustls/rustls) library on Linux. However, +on MacOS, you need a special version of the Clang tool, released from the official [wasi-sdk](https://github.com/WebAssembly/wasi-sdk), in order to support TLS libraries. + +> When you compile Rust TLS source code to Wasm on Linux, the result Wasm file is cross-platform and can run correctly on any platform with WasmEdge installed. This section is only applicable when you need to **compile** Rust TLS source code on MacOS. + +[Download the latest wasi-sdk release](https://github.com/WebAssembly/wasi-sdk/releases) for your platform and +expand it into a directory. Point the `WASI_SDK_PATH` variable to this directory and export a `CC` variable for the default Clang. + +``` +export WASI_SDK_PATH /path/to/wasi-sdk-22.0 +export CC="${WASI_SDK_PATH}/bin/clang --sysroot=${WASI_SDK_PATH}/share/wasi-sysroot" +``` + +That's it. Now you can use the `cargo` tools on MacOS to compile tokio libraries with `rust-tls` feature turned on. + diff --git a/docs/start/install.md b/docs/start/install.md index af03298d..304806d8 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -50,16 +50,16 @@ Suppose you are interested in the latest builds from the `HEAD` of the `master` #### Install WasmEdge with plug-ins -WasmEdge plug-ins are pre-built native modules that provide additional functionalities to the WasmEdge Runtime. To install plug-ins with the runtime, you can pass the `--plugins` parameter in the installer. For example, the command below installs the `wasmedge_rustls` plug-in to enable TLS and HTTPS networking. +WasmEdge plug-ins are pre-built native modules that provide additional functionalities to the WasmEdge Runtime. To install plug-ins with the runtime, you can pass the `--plugins` parameter in the installer. For example, the command below installs the `wasi_nn-ggml` plug-in to enable LLM (Large Language Model) inference. ```bash -curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- --plugins wasmedge_rustls +curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- --plugins wasi_nn-ggml ``` -To install multiple plug-ins, you can pass a list of plug-ins with the `--plugins` option. For example, the following command installs the `wasmedge_rustls` and the `wasi_nn-ggml` plug-ins. The latter enables WasmEdge to run AI inference programs on large language models such as llama2 family of LLMs. +To install multiple plug-ins, you can pass a list of plug-ins with the `--plugins` option. For example, the following command installs the `wasi_logging`` and the `wasi_nn-ggml` plug-ins. The `wasi_logging` plug-in allows the Rust [log::Log](https://crates.io/crates/log) API to compile into Wasm and run in WasmEdge. ```bash -curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- --plugins wasmedge_rustls wasi_nn-ggml +curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- --plugins wasi_logging wasi_nn-ggml ``` The installer downloads the plug-in files from the WasmEdge release on GitHub, unzips them, and then copies them over to the `~/.wasmedge/plugin/` folder (for user install) and to the `/usr/local/lib/wasmedge/` folder (for system install). @@ -123,15 +123,16 @@ If you used `winget` to install WasmEdge, the files are located at `C:\Program F WasmEdge uses plug-ins to extend its functionality. If you want to use more of WasmEdge's features, you can install WasmEdge along with its plug-ins and extensions as described below: -### TLS plug-in +### The logging plug-in -The WasmEdge TLS plug-in utilizes the native OpenSSL library to support HTTPS and TLS requests from WasmEdge sockets. To install WasmEdge with the TLS plug-in, run the following command. +The `wasi_logging` plug-in supports the [log::Log](https://crates.io/crates/log) Rust API. +It allows [log::Log](https://crates.io/crates/log) in Rust code to be compiled to Wasm and to run in WasmEdge. ```bash -curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- --plugins wasmedge_rustls +curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- --plugins wasi_logging ``` -Then, go to [HTTPS request in Rust chapter](../develop/rust/http_service/client.md) to see how to run HTTPs services with Rust. +[See more examples](https://github.com/WasmEdge/WasmEdge/tree/master/examples/plugin/wasi-logging) ### WASI-NN plug-ins @@ -240,6 +241,27 @@ curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/insta Then, go to [WASI-Crypto in Rust chapter](../develop/rust/wasicrypto.md) to see how to run WASI-crypto functions. +### WasmEdge OpenCV mini Plug-in + +The WasmEdge OpenCV Mini plug-in supports a subset of OpenCV APIs in a [Rust API](https://github.com/second-state/opencvmini). +It is essential for developing image processing / vision AI applications in WasmEdge. + +```bash +curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- --plugins wasmedge_opencvmini +``` + +[See an example](https://github.com/second-state/opencvmini-example) + +### WasmEdge zlib Plug-in + +The zlib is required for compiling and running many existing C / C++ / Rust apps in Wasm. Most noticeably, it is required for the Python port to Wasm. It supports the standard [zlib.h](https://github.com/madler/zlib/blob/develop/zlib.h) C API. + +```bash +curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- --plugins wasmedge_zlib +``` + +[See an example](https://github.com/WasmEdge/WasmEdge/tree/master/examples/plugin/wasmedge-zlib). + ### WasmEdge Image Plug-in The wasmEdge-Image plug-in can help developers to load and decode JPEG and PNG images and convert into tensors. To install this plug-in, please use the `--plugins wasmedge_image` parameter when [running the installer command](#generic-linux-and-macos). @@ -267,6 +289,22 @@ If you install this plug-in WITHOUT installer, you can [refer to here to install Then, go to [TensorFlow interface in Rust chapter](../develop/rust/wasinn/tf_plugin.md) to see how to run `WasmEdge-TensorFlow` functions. + +### TLS plug-in + + +:::note +The WasmEdge TLS plugin is being deprecated from WasmEdge 0.14.0. We now compile TLS functions directly into Wasm for better portability. +:::note + +The WasmEdge TLS plug-in utilizes the native OpenSSL library to support HTTPS and TLS requests from WasmEdge sockets. To install WasmEdge with the TLS plug-in, run the following command. + +``` +curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash -s -- -v 0.13.5 --plugins wasmedge_rustls +``` + +The HTTPS and TLS demos from 0.13.5 require the TLS plug-in. + ### WasmEdge TensorFlow-Lite Plug-in