Use Workers KV directly from Rust

In this tutorial, you will learn how to read and write to Workers KV directly from Rust, by using wasm_bindgen and a simple custom wrapper around the JS Workers KV API.

​​ Before you start

All of the tutorials assume you have already completed the Get started guide, which gets you set up with a Cloudflare Workers account, C3 , and Wrangler.

​​ Basic project scaffolding

To get started:

1. Run the git clone command to create a basic project using the rustwasm-worker template .
2. After running the git clone command, cd into the new project.
3. Use the current state of the git repository as the initial commit by running the git add and git commit commands in your terminal.

​​ Create and bind a KV namespace

To be able to access Workers KV, define a binding for a particular KV namespace in the wrangler.toml file generated in your new project’s directory. If you do not have an existing namespace, create one using wrangler. For example, a namespace called KV_FROM_RUST would be created by running:

Create a preview ID to use the namespace with wrangler preview:

Add this binding to the wrangler.toml file:

​​ Pass the KV namespace object to Rust

You can now access this KV namespace as the variable KV_FROM_RUST in JavaScript. To read or write from the namespace in Rust, you need to pass the whole object to the Rust handler function:

Note that the signature of your Rust handler differs from the template, which merely returns a String from Rust and keeps the request and response handling purely on the JavaScript side. This tutorial will try to do as much as possible in Rust and pass the request directly to the wasm handler, which will then construct and return a response.

To do this, declare web-sys as one of your Rust dependencies and explicitly enable the Request, Response and ResponseInit features (the Url and UrlSearchParams features will be used later in this tutorial):

You can now use Request and Response in Rust to create a very simple handler that completely ignores the request and always responds with a 200 OK status:

​​ Bind to KV using wasm_bindgen

You are now ready to create a type binding using wasm_bindgen to access the KV object. Since the KV API returns JavaScript promises, you must first add wasm-bindgen-futures and js-sys as dependencies:

Add the wrapper and change the type of the kv argument of your handler accordingly:

​​ Create a wrapper around KV

You could start using the kv parameter as is, but the function signatures generated by wasm_bindgen can be difficult to work within Rust. For an easier experience, create a simple struct around the WorkersKvJs type that wraps it with a more Rust-friendly API:

The above wrapper only exposes a subset of the options supported by the KV API, other options such as expiration instead of expirationTtl for PUT and other types than text and arrayBuffer for GET could be wrapped in a similar fashion. Conceptually, the wrapper methods all manually construct a JavaScript object using Reflect::set and then convert the return value into a standard Rust type where necessary.

​​ Use the wrapper

You are now ready to use the wrapper to read and write values to and from your KV namespace.

The following function is an example handler that writes to KV on a PUT request, using the URL segments to determine the KV document’s key name and value. For example, sending a PUT request to /foo?value=bar will write the "bar" value to the foo key.

Additionally, the example handler will read from KV when on GET requests, using the URL pathname as the key name. For example, a GET /foo request will return the foo key’s value, if any.

The finalized handle function:

You can use wrangler dev to test the Worker:

​​ Conclusion

With all previous steps complete, the final lib.rs should look as follows (you can also find the full code as an example repository at https://github.com/fkettelhoit/workers-kv-from-rust ):