Getting Started with Rust Cloudflare Workers

Rodney Lab - Apr 25 '22 - - Dev Community

☁️ Why use Rust Cloudflare Workers?

In this article, we have a look at getting started with Rust Cloudflare Workers. We build out a basic serverless API with router. Before we get into that, though, you might be asking why use serverless Rust? Especially if you already know JavaScript. After all, much of the functionality we would want to implement can also be implemented with JavaScript. For me, however, the motivation is learning Rust. Rust tooling is increasing prevalent, in the Web Development sphere. Examples are swc and Parcel.js. swc compiles TypeScript and JavaScript, and bundles twenty times faster than Babel. Parcel.js saw a 10 times speed improvement moving to the new Rust implementation.

Of course, you might not see these speed improvements in serverless functions. That said, serverless functions are usually small pieces of code which perform a single small task. To me, that makes them a great choice for learning Rust. You can invest small chunks of your time on focussed code, starting with a simple Rust Cloudflare Worker. Then either as the initial functions evolve and require more sophisticated solutions, or indeed, as you consider solving other more detailed problems using Workers, you can gradually improve your Rust understanding.

🧑🏽‍🎓 Learning in Public

I should point out I am still relatively new to Rust, so you might know of better Rust implementations of the Rust code below. In fact, I would love feedback on how I could improve the Rust code (drop comments below or add pull requests to the demo code repo). Instead of best practice Rust, this is more of a guide on how to get up and running with Rust Cloudflare Workers, where I share some of the Rust I have learned. That said, I hope you can benefit from the post if you already know Rust, but want to know how to get going with Rust Cloudflare Workers.

📚 Rust Learning Resources

If you are learning Rust, here are some free resources you might find useful:

  • The Rust Programming Language book — normally just referred to as “The Book” is probably the best starting point. Available online as a number of chapters, it offers a gentle introduction to Rust. Also try Rust by Example, to help push home concepts in the Book, especially if you prefer a more hands-on approach to learning.
  • Rustlings — a collection of small exercises you can run through to improve your Rust. Consider this if you prefer a more practical approach to learning, rather than reading the book.
  • Rust Cookbook — you will probably use this differently to the other two resources. Rather than work through from start to finish, it is quite handy to dive in to a particular area you need for a problem you are looking at, which you have not yet seen in Rust.

If you prefer videos, Chris Biscardi is behind Rust Adventures which provides another avenue to learning Rust. You can access much of the content for free. Chris is very knowledgable in Rust and I have, in fact, picked up quite a bit from his blog posts.

🧱 Getting Started with Rust Cloudflare Workers: What we’re Building

We will start by scaffolding the new Rust Cloudflare Worker, setting up all the necessary tooling. Once we have our hello, world running, we add a router with a health check route. Adding more features, we learn a little more about use Rust with Workers, wrapping up with a final message API route which can listen for and parse JSON POST requests.

⚙️ Rust Setup

You can set up Rust with Homebrew or other package managers. Rust’s recommended approach though, is to install from the Terminal from their script:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Enter fullscreen mode Exit fullscreen mode

This installs rustup, which manages your Rust installation. You could use the following command to update your Rust tooling (when the next release is available, for example):

rustup update
Enter fullscreen mode Exit fullscreen mode

For now, we want to be able to cross-compile Rust code into WASM, and will use rustup to add the tooling, locally for us:

rustup target add wasm32-unknown-unknown
Enter fullscreen mode Exit fullscreen mode

🔧 Serverless Rust Cloudflare Worker Setup

Clone the Cloudflare Rust Worker template using pnpm:

pnpm dlx wrangler generate \\
    getting-started-rust-cloudflare-workers \\
    https://github.com/cloudflare/workers-sdk/templates/experimental/worker-rust
Enter fullscreen mode Exit fullscreen mode

You should now have a new getting-started-rust-cloudflare-workers directory containing:

  • src/lib.rs: your Rust worker source file
  • Cargo.toml: Rust’s package meta file (analogous to Node’s package.json)
  • package.json: Node package.json file with worker development and deploy scripts
  • wrangler.toml: the Wrangler config

📦 Package Meta

Start by customizing the Cargo.toml for our project:

[package]
name = "my-rust-cloudflare-worker"
version = "0.1.0"
edition = "2021"
authors = ["Robert Fullman <robert@example.com>"]
description = "My first Rust Cloudflare Worker"
repository = "https://github.com/example-profile/my-rust-cloudflare-worker"
license = "BSD-3-Clause"
Enter fullscreen mode Exit fullscreen mode

Currently, the template does not include the last four lines shown, but you may like to include them, to follow best practice (adapting to suit your needs). Also, update the name field to match the project name.

🖥 Dev environment

To install Wrangler locally, within the project, from your project directory, run the command:

pnpm install
Enter fullscreen mode Exit fullscreen mode

Wrangler is Cloudflare’s worker tooling. Fire up the dev environment from the Terminal:

wrangler dev
Enter fullscreen mode Exit fullscreen mode

pnpm dev: screenshot shows Terminal with output showing the worker is listening on 0.0.0.0:8787

Cargo will compile the code in src/lib.rs. This will be a little slow this first time. When compilation completes, you will see a message like Listening on 0.0.0.0:8787 in the Terminal. With Wrangler running, you can jump to your browser by pressing the B key, or alternatively typing http://127.0.0.1:8787 in your preferred browser address bar. Either way, you should get a “Hello, World” message.

Getting Started with Rust Cloudflare Workers: Wrangler Update: screenshot shows a browser window with the words "Hello, World!" in white on a black background.

🦀 Rust Coding

It would be nice to get a little log printed to the console on each request. Update the Rust source code in src/lib.rs, adding a logging function:

use worker::*;

fn log_request(req: &Request) {
    console_log!(
        "{} - [{}], located at: {:?}, within: {}",
        Date::now().to_string(),
        req.path(),
        req.cf().coordinates().unwrap_or_default(),
        req.cf().region().unwrap_or("unknown region".into())
    );
}

#[event(fetch)]
async fn main(req: Request, env: Env, ctx: Context) -> Result<Response> {
    log_request(&req);
    Response::ok("Hello, World!")
}
Enter fullscreen mode Exit fullscreen mode

Getting Started with Rust Cloudflare Workers: Wrangler Console Log: screenshot shows Terminal with wrangler running last lines log a recent request, showing timestamp, route (which is "/"), approximate user coordinates and country (England).

Refresh the browser, and you should see a little log appear. This is handy for debugging, though in production, you might consider a serverless logging provider for your API, like Logtail.

🚢 Cargo tools

A feature that sets Rust apart from other languages is the helpfulness of the compiler. Although the code works as it is, try running:

cargo check
Enter fullscreen mode Exit fullscreen mode

Getting Started with Rust Cloudflare Workers: Cargo check: screenshot shows Terminal user has typed "cargo check". Feedback includes warnings on the env and ctx variables being unused. Feedback is detailed with line numbers for the source code and clear annotations showing the exact word the warnings pertain to.

You will get some linting tips! For next-level linting, try Clippy. You won’t see a difference for our short snippet, but generally it will go the extra mile in helping you write more idiomatic Rust.

rustup component add clippy
cargo clippy
Enter fullscreen mode Exit fullscreen mode

The first command is a one-off piece of setup, installing Clippy, if it is not already on your system.

Finally, here is another tool in the Rust tool chain; this time for formatting your code:

cargo fmt
Enter fullscreen mode Exit fullscreen mode

🛣️ Adding Some Routes

For an API, you will, typically, need more than a single route. We can set up the typical health_check route on a router for our worker:

#[event(fetch)]
async fn main(req: Request, env: Env, ctx: Context) -> Result<Response> {
    log_request(&req);
    let router = Router::new();

    router
        .get("/health_check", |_, _| Response::ok("OK"))
        .run(req, env)
        .await
}
Enter fullscreen mode Exit fullscreen mode

Router here comes from the worker crate. We do not need to import it explicitly as, in line 1 of src/lib.rs, we bring all structs from worker into scope.

🍃 Environment Variables

Rust procedural macros provide syntactic sugar for common tasks. Let’s see a couple here. First, we can extract meta from the Cargo.toml file using the env! macro. The current package version will be handy if you are putting together the API docs, for example. Access the package version using CARGO_PKG_VERSION:

#[event(fetch)]
async fn main(req: Request, env: Env, ctx: Context) -> Result<Response> {
    log_request(&req);
    let router = Router::new();

    router
        .get("/health_check", |_, _| Response::ok("OK"))
        .get("/api-version", |_,_| {
           let version = env!("CARGO_PKG_VERSION");
           Response::ok(format!("API version: {version}"))
        })
        .run(req, env)
        .await
}
Enter fullscreen mode Exit fullscreen mode

Notice, we used format! (another procedural macro) to build the response using an interpolated string.

📮 POST Requests

We have only looked at REST GET requests so far. Let’s create a basic message route, listening for JSON POST requests. If you are just starting out in Rust, you will quickly find one of the most useful crates (Rust packages) is Serde (a contraction of serialize and deserialize). We will use it here to parse the JSON request body, and you will find there are YAML and plenty of other alternatives.

Getting Started with Rust Cloudflare Workers: adding Dependencies

To add a crate to your project, you just update Cargo.toml, including the version number for the crate:

[dependencies]
serde = "1"
worker = "0.0.15"

# TRUNCATED...
Enter fullscreen mode Exit fullscreen mode

Currently, cargo fmt will format Rust source only and not Cargo.toml, but you can install and configure the dprint code formatter (written in Rust) if you want that formatted too:

cargo install --locked dprint
Enter fullscreen mode Exit fullscreen mode

Rust derive Procedural Macros

Serde uses a derive macro; this is a different type of Rust procedural macro to env! and format! function-like procedural macros seen earlier. derive macros again provide syntactic sugar; under the hood, our convenient, clean code will get re-written, by Serde, to something more verbose and a little unwieldy!

To bring the Serde Deserialize macro into scope, add this line at the top of src/lib.rs:

use serde::Deserialize;
use worker::*;
Enter fullscreen mode Exit fullscreen mode

Next, with Rust being a typed language, we want to define the types for the JSON data we are expecting to receive. Add this struct in src/lib.rs defining the Message:

#[derive(Deserialize)]
struct Message {
    name: String,
    email: String,

    #[allow(dead_code)]
    message: String,
}
Enter fullscreen mode Exit fullscreen mode

In production code, we would use message as well as name and email. However, here we just do a quick console log. The line: #[allow(dead_code)] is an instruction to Cargo linting tools to ignore the fact that message exists on the Message struct, but is never used.

If you are curious to see what the expanded derive macro code looks like, set up and run the cargo-expand tool. This uses some unstable Rust features, so run rustup toolchain install nightly --allow-downgrade to make the nightly toolchain available locally before running cargo expand for the first time.

POST Route Code

Finally, add a POST route to the main function, to listen for messages:

#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    log_request(&req);
    let router = Router::new();

    router
        .get("/health_check", |_, _| Response::ok("OK"))
        .get("/api-version", |_, _| {
            let version = env!("CARGO_PKG_VERSION");
            Response::ok(format!("API version: {version}"))
        })
        .post_async("/message", |mut req, _| async move {
            let Message { name, email, .. } = match req.json().await {
                Ok(value) => value,
                Err(_) => return Response::error("Bad request", 400),
            };
            console_log!("New message from {name} ({email})");
            Response::ok(format!("Thanks {name}, we'll be in touch!"))
        })
        .run(req, env)
        .await
}
Enter fullscreen mode Exit fullscreen mode

We use a console_log! macro provided by the worker crate to print the message to the console. In general, in Rust code, you will use println! or dbg! instead. Be careful no to log Personal Identifiable Information (PII), and be sure to comply with legal requirements. We only include the fictitious email here to demonstrate Rust features. Be sure to protect any real user data you work with. You might consider using the secrecy crate for such private data, which will help you obfuscate PII, by default, and opt-in to reveal the data to authorized users.

💯 Getting Started with Rust Cloudflare Workers: Check your Work

You can check this new POST route work by sending a message using curl in a separate tab:

curl http://localhost:8787/message \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "Margaret Falls",
    "email": "margaret@example.com",
    "message": "Hello, everybody!"
}'
Enter fullscreen mode Exit fullscreen mode

Getting Started with Rust Cloudflare Workers: Message Log: screenshot shows Terminal running Wrangler. A recent request log is visible, with request details listed. Below, on a separate line, is the message "New message from Margaret Falls (margaret@example.com)"

🙌🏽 Getting Started with Rust Cloudflare Workers: Wrapping Up

We have learned all about getting started with Rust Cloudflare Workers in this post. More specifically, we have seen:

  • how to set up Cloudflare Rust worker tooling;
  • how you can create a Rust worker API router; and
  • some worker features like console_log.

The Getting started with Rust Cloudflare Workers demo code is in the Rodney Lab GitHub repo.

I hope you found this article useful and am keen to hear where you will go next, as well as potential improvements, both to the Rust code and explanations above.

🙏🏽 Getting Started with Rust Cloudflare Workers: Feedback

Have you found the post useful? Would you prefer to see posts on another topic instead? Get in touch with ideas for new posts. Also, if you like my writing style, get in touch if I can write some posts for your company site on a consultancy basis. Read on to find ways to get in touch, further below. If you want to support posts similar to this one and can spare a few dollars, euros or pounds, please consider supporting me through Buy me a Coffee.

Finally, feel free to share the post on your social media accounts for all your followers who will find it useful. As well as leaving a comment below, you can get in touch via @askRodney on Twitter and also askRodney on Telegram. Also, see further ways to get in touch with Rodney Lab. I post regularly on Astro as well as SvelteKit. Also, subscribe to the newsletter to keep up-to-date with our latest projects.

Image
how i built a local first audio transcription: building a privacy-first voice processing pipeline

ai, llm, privacy, opensource
Image
JUAL WALL PANEL UNTUK RUANG TAMU
Image
Exoplanet Resource Market: Unlocking the Potential of Other Worlds
Image
Learn About Orlando Accident Lawyers While You Work From At Home
Image
tehnik meraih kemenangan di slots online 3d
Image
Cat Flap Fitters
Image
dua trick mustajab jadi pemenang slots online secara mengesankan.
Image
5 Laws That Can Benefit The Mental Health Assessments Industry
Image
The Three Greatest Moments In Top Accident Attorneys History
Image
What Is Self Propelled Wheelchair Uk? And How To Make Use Of It
Image
Why Local Accident Attorneys Is Fast Becoming The Trendiest Thing Of 2023?
Image
Why Local Accident Attorneys Will Be Your Next Big Obsession
Image
【張長處 1958年，席捲世界的易遊娛樂麻雀「清零」是如何終結的？7】
Image
Undisputed Proof You Need Locked Out Of Car No Spare Key
Image
9 Signs That You're An Expert Built In Electric Fireplace Wall Expert
Image
Green Hydrogen for Grid Balancing: A Sustainable Solution to Energy Instability
Image
A Step-By-Step Guide For Choosing The Right Asbestos Lawsuit Settlement
Image
From All Over The Web The 20 Most Amazing Infographics About Electric Wall Fireplace
Image
15 Trends That Are Coming Up About Self Propelled Wheelchairs Uk
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .