Rust on the Compute platform
The Compute platform supports application code written in Rust, a fast and memory-efficient language for building performant applications.
Quick access
Project layout
If you don't yet have a working toolchain and Compute service set up, start by getting set up.
At the end of the initialization process, the current working directory will contain a file tree resembling the following:
├── .cargo├── .gitignore├── Cargo.lock├── Cargo.toml├── README.md├── fastly.toml├── rust-toolchain.toml└── src └── main.rs
The most important file to work on is src/main.rs
, which contains the logic you'll run on incoming requests. If you initialized your project from the default starter template, the contents of this file should match the one in the template's repository. The other files include:
- Cargo metadata:
Cargo.toml
andCargo.lock
describe the dependencies of your package, managed using Cargo, Rust's package manager. - Fastly metadata: The
fastly.toml
file contains metadata required by Fastly to deploy your package to a Fastly service. It is generated by the fastly compute init command. Learn more aboutfastly.toml
. - Rust toolchain: The
rust-toolchain.toml
file specifies that the compiler should produce a WebAssembly binary and which version of Rust to use.
Main interface
The most common way to start a Compute program is to define a main()
function with the #[fastly::main]
attribute and the following type signature:
2346
#[fastly::main]fn main(req: Request) -> Result<Response, Error> { // ... }
HINT: Use of the #[fastly::main]
macro creates a simple interface in which the main function of your program receives a request and returns a response. However, there are use cases where this is not necessarily a good fit, such doing more work after starting to send the response to the client. If you wish, you may define a conventional main function and use fastly::Request::from_client
and fastly::Response::send_to_client
(or fastly::Response::stream_to_client
) instead.
The main fastly crate provides the core Request
, Body
, ResponseExt
, and Error
types referenced here. The program will be invoked for each request that Fastly receives for a domain attached to your service, and it must return a response that can be served to the client.
Communicating with backend servers and the Fastly cache
A fastly::Request
can be forwarded to any backend defined on your service. If you specify a backend hostname as part of completing the fastly compute deploy wizard, it will be named the same as the hostname or IP address, but with .
replaced with _
(e.g., 151_101_129_57
). It's a good idea to define backend names as constants:
const BACKEND_NAME: &str = "my_backend_name";
And then reference them when you want to forward a request to a backend:
78
req.set_ttl(60); Ok(req.send(BACKEND_NAME)?)
Requests forwarded to a backend will typically transit the Fastly cache, and the response may come from cache. For more precise or explicit control over the Fastly edge cache see Caching content with Fastly.
The Rust SDK supports dynamic backends created at runtime using the BackendBuilder
.
Responses returned from the send
method are compatible with the return type of main
, so a minimal implementation of a Compute service that acts as a standard HTTP caching proxy between the client and the backend is:
12345678
use fastly::{Error, Request, Response};
const BACKEND_NAME: &str = "my_backend_name";
#[fastly::main]fn main(req: Request) -> Result<Response, Error> { Ok(req.send(BACKEND_NAME)?)}
Composing requests and responses
In addition to the request passed into main()
and responses returned from send()
, requests and responses can also be constructed. This is useful if you want to make an arbitrary API call that is not derived from the client request, or if you want to make a response to the client without making any backend fetch at all.
The Request
struct can be used as a builder, to chain methods that customize the request:
let req = Request::post("https://example.com/api/getFlags").with_header("some-header", "someValue");
Similarly, Response
has several static methods that create a new response:
5
Ok(Response::from_body("Hi from the edge"))
Parsing and transforming responses
Requests and responses in Compute services are streams, which allows large payloads to move through your service without buffering or running out of memory. Conversely, running methods such as into_string
on a Body
will force the stream to be consumed entirely into memory. This can be appropriate where a response is known to be small or needs to be complete to be parsable.
This example will read a backend response into memory, replace every occurrence of "cat" with "dog" in the body, and then create a new body with the transformed string:
let api_req = Request::get("https://host/api/checkAuth"); let mut beresp = api_req.send("example_backend")?; let beresp_body = beresp.take_body();
// Take care! into_string() will consume the entire body into memory, and replace() // will futher double the memory requirement let new_body = beresp_body.into_string().replace("cat", "dog");
beresp.set_body(new_body);
However, it is often better to avoid buffering responses in this way. Peeking at the beginning of the stream can be useful for some use cases; this example identifies when a response stream begins with the WebAssembly 'magic number':
const MAGIC: &[u8] = b"\0asm"; let prefix = beresp_body.get_prefix_mut(MAGIC.len()); if prefix.as_slice() == MAGIC { println!("might be Wasm!"); }
Parsing responses in Rust usually benefits from well tested dependencies such as serde_json
which works well on the Compute platform. This example tries to consume the body as a JSON value, but only up to the first 4KiB. Using take()
here avoids writing the bytes back to the body unnecessarily:
let prefix = beresp_body.get_prefix_mut(4096).take(); if let Ok(_json) = serde_json::from_slice::<serde_json::Value>(&prefix) { println!("valid json!"); }
Other crates known to be useful for transforming or composing responses include lolhtml
and horrorshow
.
Compression
Fastly can compress and decompress content automatically, and it is often easier to use these features than to try to perform compression or decompression within your Rust code. Learn more about compression with Fastly.
Using edge data
Fastly allows you to configure various forms of data stores to your services, both for dynamic configuration and for storing data at the edge. The Rust SDK exposes the kv_store
, config_store
and secret_store
modules to allow access to these APIs.
All edge data resources are account-level, service-linked resources, allowing a single store to be accessed from multiple Fastly services.
Logging
The log-fastly
crate provides a standardized interface for sending logs to Fastly real-time logging, which can be attached to many third-party logging providers. Log endpoints are referenced in your code by name:
log_fastly::init_simple("my_endpoint_name", log::LevelFilter::Warn);log::warn!("This will be written to my_endpoint...");log::info!("...but this won't");
If your code panics, output will be emitted to stderr
. You can override this behavior by specifying an endpoint to use for Rust panics with fastly::log::set_panic_endpoint
:
fastly::log::set_panic_endpoint("my_error_endpoint").unwrap();panic!("oh no!");// => logs "panicked at 'oh no', your/file.rs:line:col" to "my_error_endpoint"
Using dependencies
The Compute build process compiles your code to WebAssembly and uses the WebAssembly System Interface (WASI). Because of this, it supports WASI-compatible Rust crates. To get an idea of whether a crate will work with WASI, build it using cargo build --target=wasm32-wasi
. If it fails, it is not currently compatible. If it succeeds, still note that some crates may use conditional compilation to exclude functionality on Wasm, or include stub implementations that fail at runtime.
Our Fiddle tool allows the use of a subset of crates that we have tested and confirmed will work on the Compute platform:
- regex (1.10.5)
- sha1 (0.10.6)
- percent-encoding (2.3.1)
- base64 (0.22.1)
- hashring (0.3.5)
- image (0.25.1)
- qrcode-generator (4.1.9)
- urlencoding (2.1.3)
- url (2.5.2)
- esi (0.4.2)
- htmlescape (0.3.1)
- rust-crypto-wasm (0.3.1)
- qrcode (0.14.1)
- serde_json (1.0.120)
- anyhow (1.0.86)
- crc_all (0.2.2)
- time (0.3.23)
- glob (0.3.1)
- robotstxt (0.3.0)
- sha2 (0.10.8)
- cookie (0.18.1)
- sha256 (1.5.0)
- hmac (0.12.1)
- hex (0.4.3)
- jwt-simple (0.12.9)
- tinytemplate (1.2.1)
- log-fastly (0.10.2)
- hmac-sha512 (1.1.5)
- serde_urlencoded (0.7.1)
- once_cell (1.19.0)
- serde (1.0.204)
- md5 (0.7.0)
- geoutils (0.5.1)
- log (0.4.22)
- md-5 (0.10.6)
- chrono (0.4.38)
- quick-xml (0.36.0)
- m3u8-rs (6.0.0)
- rand (0.8.5)
- hmac-sha1 (0.2.2)
- uuid (1.10.0)
- lol_html (1.2.1)
- env_logger (0.11.3)
- libflate (2.1.0)
- fastly (0.10.2)
- hmac-sha256 (1.1.7)
- lazy_static (1.5.0)
- kamadak-exif (0.5.5)
- tera (1.20.0)
This is a tiny fraction of the crates which will work on the Compute platform, but these are the most commonly useful crates when building applications.
Access to the client request, creating requests to backends, the Fastly cache, and other Fastly features are exposed via Fastly's own public crates:
fastly
- Core interfaces, provides access to client request, backend fetches and cachinglog-fastly
- Interface to Real time log streaming
Testing and debugging
Logging is the main mechanism to debug Compute programs. Log output from live services can be monitored via live log tailing. The local test server and Fastly Fiddle display all log output automatically. See Testing & debugging for more information about choosing an environment in which to test your program.
Most common logging requirements involve HTTP requests and responses. It's important to do this in a way that doesn't affect the main program logic, since consuming a request or response body can only be done once. The following example demonstrates a println!
statement for request headers, response headers, request body and response body:
Since the bodies of HTTP requests and responses in Compute services are streams, we are using the try_get_body_prefix_str
method to 'spy' on the response without consuming it.
Unit testing
Due to Fastly's custom WASI hostcalls, some setup is required in order to run Rust unit tests in a way you might be used to. By default, the environment created by cargo test
doesn't expose the Fastly hostcalls and instead panics when there is an attempt to read a value from a type that is provided by the fastly
crate.
In order to provide these types, you can use a special run-mode on our local development server to run each individual test and use cargo-nextest
to handle the surrounding orchestration. To do that, you will need to install the local testing server independently of the Fastly CLI, and modify your cargo.toml
. Full instructions can be found in the testing server's GitHub repository. This will enable you to use cargo nextest run
to run unit tests that use the Fastly crate.