Expand description

Rust SDK for Compute@Edge.

This Rustdoc page is a reference for how to use individual APIs from this SDK. For a guide-level introduction to using Compute@Edge with this SDK, see Rust on Compute@Edge at the Fastly Developer Hub.

Migrating from SDK version 0.5.* and earlier

Version 0.6.0 introduced some substantial changes to the API to improve convenience, capability, and discoverability. While there are many changed names and new types, the execution model of a Compute@Edge program has not changed. This guide highlights the changes that most existing Compute@Edge programs will need to make in order to work with the improved API.

New Request and Response; no more RequestExt and ResponseExt

Replace Request<Body> with Request, and Response<Body> with Response, and then remove references to RequestExt and ResponseExt.

In previous versions of the API, Request and Response were provided by the third-party http crate. While those types are flexible enough to represent Compute@Edge HTTP values, the new types are purpose-built for Compute@Edge and include a number of conveniences, such as automatic conversion of method argument types and built-in support for JSON and form data. Methods like Request::send() that were previously in the extension traits RequestExt and ResponseExt are now defined directly on the types, so those traits are no longer needed.

For example, a minimal program using #[fastly::main] now looks like:

use fastly::{Error, Request, Response};

#[fastly::main]
fn main(ds_req: Request) -> Result<Response, Error> {
    Ok(ds_req.send("example_backend")?)
}

“Client” instead of “downstream”

Call Request::from_client() to get the client request, instead of the previous fastly::downstream_request() function.

Other functions and methods that used “downstream” to refer to the client that makes the initial HTTP request now also use “client”. For example, Response::send_downstream() is now Response::send_to_client(), and downstream_client_ip_addr() is now Request::get_client_ip_addr().

Header methods instead of HeaderMap

Access headers directly through Request and Response, rather than through http::header::HeaderMap. For example, code that previously looked like:

let my_val = req.headers().get(header_name);
req.headers_mut().insert(other_header_name, header_value);

Should now look like:

let my_val = req.get_header(header_name);
req.set_header(other_header_name, header_value);

Automatic argument conversion

Pass trusted string literals and other similar types to functions like Request::get_header() directly, rather than converting them explicitly.

In previous Compute@Edge programs, it was very common to see code like:

HeaderName::try_from("my-header").unwrap()

This has an explicit type conversion and error handling, despite the fact that we know the string "my-header" will always be a valid header name.

Many method arguments now have types like impl ToHeaderName rather than HeaderName, allowing you to mix and match strings, byte vectors, and other types into your argument types with conversions performed automatically. See the documentation of the convert module’s traits like ToHeaderName for details about which types can be converted, and when to watch out for panics.

Builder-style methods on Request and Response

Remove uses of http::request::Builder and http::response::Builder, and use the methods of Request and Response prefixed by with_ to use builder-style method chaining. For example:

Request::get("https://example.com")
    .with_header("my-header", "hello!")
    .with_header("my-other-header", "Здравствуйте!")
    .send("example_backend")?;

There are still non-builder-style getter and setter methods on Request and Response, so you can mix and match styles. For example:

let mut req = Request::get("https://example.com").with_header("my-header", "hello!");
if needs_translation {
    req.set_header("my-other-header", "Здравствуйте!");
}
req.send("example_backend")?;

Methods to read and modify prefixes of HTTP bodies

Rather than buffering entire bodies with methods like Body::into_bytes() or Body::into_string(), you can use a new set of methods to inspect and modify a certain number of bytes from the beginning of the body:

These methods automatically write the modified prefix back to the front of the body, making them ideal for situations where you want to inspect and possibly change some metadata at the beginning of a file. See the methods’ documentation for examples.

Modules

Convenient conversion traits.

Dictionaries for Compute@Edge.

Error-handling utilities.

Experimental Compute@Edge features.

Geographic data for IP addresses.

Low-level interfaces to the Compute@Edge APIs.

Compute@Edge HTTP interfaces.

Automatically enforced limits for HTTP components.

Low-level interface to Fastly’s Real-Time Log Streaming endpoints.

Media types (also known as Multipurpose Internet Mail Extensions or MIME types).

Macros

Send a response to the client with the given HTTP status code, and then panic.

Structs

A named backend.

An HTTP body that can be read from, written to, or appended to another body.

A Compute@Edge Dictionary.

The Error type, a wrapper around a dynamic error type.

An HTTP request, including body, headers, method, and URL.

An HTTP response, including body, headers, and status code.

Attribute Macros

Main function attribute for a Compute@Edge program.