Skip to main content

Create a Rust worker

Rust workers are compiled into a Wasm module. Then, they are loaded by Wasm Workers Server and start processing requests.

Your first worker

Every worker receives a Request<String> struct and returns a Response<Content>. These structs come from the widely known http crate and the Content struct is defined in our rust kit. It allows you returning different types. Finally, the worker macro connects your worker with wws.

In this example, the worker will get a request and print all the related information.

  1. Create a new Rust project:

    cargo new --name worker worker
  2. Add the dependencies to the Cargo.toml file:

    Cargo.toml
    [package]
    name = "worker"
    version = "0.1.0"
    edition = "2021"

    [dependencies]
    anyhow = "1.0.63"
    wasm-workers-rs = { git = "https://github.com/vmware-labs/wasm-workers-server/" }
  3. Add the reply function to the src/main.rs file. You will need to import the required resources from the wasm-workers-rs crate and use the worker macro:

    src/main.rs
    use anyhow::Result;
    use wasm_workers_rs::{
    worker,
    http::{self, Request, Response},
    Content,
    };

    #[worker]
    fn reply(req: Request<String>) -> Result<Response<Content>> {
    Ok(http::Response::builder()
    .status(200)
    .header("x-generated-by", "wasm-workers-server")
    .body(String::from("Hello wasm!").into())?)
    }
  4. Now, you can add all the information from the given Request struct:

    src/main.rs
    use anyhow::Result;
    use wasm_workers_rs::{
    worker,
    http::{self, HeaderValue, Request, Response},
    };

    #[worker]
    fn reply(req: Request<String>) -> Result<Response<String>> {
    // Applied changes here to use the Response method. This requires changes
    // on signature and how it returns the data.
    let response = format!(
    "<!DOCTYPE html>
    <body>
    <h1>Hello World</h1>
    <p>Replying to {}</p>
    <p>Method: {}</p>
    <p>User Agent: {}</p>
    <p>Body: {}</p>
    <p>This page was generated by a Wasm modules built from Rust.</p>
    </body>",
    req.uri(),
    req.method().as_str(),
    req.headers()
    .get("user-agent")
    .unwrap_or(&HeaderValue::from_str("None").unwrap())
    .to_str()
    .unwrap(),
    req.body()
    );

    Ok(http::Response::builder()
    .status(200)
    .header("x-generated-by", "wasm-workers-server")
    .body(response.into())?)
    }
  5. In this case, you need to compile the project to Wasm (WASI):

    # Install the component and build
    rustup target add wasm32-wasi && \
    cargo build --release --target wasm32-wasi
  6. Run your worker with wws. If you didn't download the wws server yet, check our Getting Started guide.

    cd target/wasm32-wasi/release && \
    wws .

    ⚙️ Loading routes from: .
    🗺 Detected routes:
    - http://127.0.0.1:8080/worker
    => worker.wasm (name: default)
    🚀 Start serving requests at http://127.0.0.1:8080
  7. Finally, open http://127.0.0.1:8080/worker in your browser.

Add a Key / Value store

Wasm Workers allows you to add a Key / Value store to your workers. Read more information about this feature in the Key / Value store section.

To add a KV store to your worker, follow these steps:

  1. Create a new Rust project:

    cargo new --name worker-kv worker-kv
  2. Add the dependencies to the Cargo.toml file:

    Cargo.toml
    [package]
    name = "worker-kv"
    version = "0.1.0"
    edition = "2021"

    [dependencies]
    anyhow = "1.0.63"
    wasm-workers-rs = { git = "https://github.com/vmware-labs/wasm-workers-server/" }
  3. Add the reply function to the src/main.rs file. You will need to import the required resources from the wasm-workers-rs crate and use the worker macro. In this case, we will add a new attribute to the worker macro called cache and update the function signature:

    src/main.rs
    use anyhow::Result;
    use wasm_workers_rs::{
    worker,
    http::{self, Request, Response},
    Content,
    };

    #[worker(cache)]
    fn handler(_req: Request<String>, cache: &mut Cache) -> Result<Response<Content>> {
    Ok(http::Response::builder()
    .status(200)
    .header("x-generated-by", "wasm-workers-server")
    .body(String::from("Hello wasm!").into())?)
    }
  4. Then, let's read a value from the cache and update it:

    src/main.rs
    use anyhow::Result;
    use wasm_workers_rs::{
    worker,
    http::{self, Request, Response},
    Cache, Content,
    };

    #[worker(cache)]
    fn handler(_req: Request<String>, cache: &mut Cache) -> Result<Response<Content>> {
    // Applied changes here to use the Response method. This requires changes
    // on signature and how it returns the data.
    let count = cache.get("counter");
    let count_num = match count {
    Some(count_str) => count_str.parse::<u32>().unwrap_or(0),
    None => 0,
    };

    let response = format!(
    "<!DOCTYPE html>
    <body>
    <h1>Key / Value store in Rust</h1>
    <p>Counter: {}</p>
    <p>This page was generated by a Wasm modules built from Rust.</p>
    </body>",
    count_num
    );

    cache.insert("counter".to_string(), (count_num + 1).to_string());

    Ok(http::Response::builder()
    .status(200)
    .header("x-generated-by", "wasm-workers-server")
    .body(response.into())?)
    }
  5. Compile the project to Wasm (WASI):

    # Install the component and build
    rustup target add wasm32-wasi && \
    cargo build --release --target wasm32-wasi
  6. Create a worker-kv.toml file with the following content. Note the name of the TOML file must match the name of the worker. In this case we have worker-kv.wasm and worker-kv.toml in the same folder (target/wasm32-wasi/release):

    target/wasm32-wasi/release/worker-kv.toml
    name = "workerkv"
    version = "1"

    [data]
    [data.kv]
    namespace = "workerkv"
  7. Run your worker with wws. If you didn't download the wws server yet, check our Getting Started guide.

    cd target/wasm32-wasi/release && \
    wws .

    ⚙️ Loading routes from: .
    🗺 Detected routes:
    - http://127.0.0.1:8080/worker-kv
    => worker-kv.wasm (name: default)
    🚀 Start serving requests at http://127.0.0.1:8080
  8. Finally, open http://127.0.0.1:8080/worker-kv in your browser.

Read environment variables

Environment variables are configured via the related TOML configuration file. These variables are accessible via std::env in your worker. To read them, just use the same name you configured in your TOML file:

envs.toml
name = "envs"
version = "1"

[vars]
MESSAGE = "Hello 👋! This message comes from an environment variable"

Now, you can read the MESSAGE variable using the std::env Rust library:

src/main.rs
use anyhow::Result;
use std::env;
use wasm_workers_rs::{
worker,
http::{self, Request, Response},
Content,
};

#[worker]
fn handler(req: Request<String>) -> Result<Response<Content>> {
// Read the environment variable using the std::env::var method
let message = env::var("MESSAGE").unwrap_or_else(|_| String::from("Missing message"));

let response = format!(
"The message is: {}",
message,
);

Ok(http::Response::builder()
.status(200)
.body(response.into())?)
}

If you prefer, you can configure the environment variable value dynamically by following these instructions.

Other examples