Fastly Compute Rust

This module enables the use of DataDome Bot Protection on the Fastly Compute platform, for services written in Rust. It is distributed as the datadome-fastly-compute crate.

Looking for the JavaScript version? See Fastly Compute.

Installation

Prerequisites

• Fastly CLI installed and configured.

• A Rust toolchain 1.85+ with the wasm32-wasip1 target:

  Shell

  rustup target add wasm32-wasip1

Protect your traffic

Update an existing Rust Compute service to start protecting your traffic with DataDome Bot Protection:

1. Add the crate to your Cargo.toml:

   TOML

   [dependencies]
   datadome-fastly-compute = "1.0.0"

2. In your entry file (src/main.rs), hand every request to the module before your own logic:

   Rust

   use datadome_fastly_compute::DataDome;
   use fastly::{Error, Request, Response};
   
   #[fastly::main]
   fn main(req: Request) -> Result<Response, Error> {
       DataDome::new()
           .on_allowed_request(|req| {
               // Current processing of your service.
               // This code is executed when the request is allowed, or when DataDome
               // could not analyse it: it receives the request (carrying the DataDome
               // enriched headers when DataDome returned them) and must send it to
               // your origin backend.
               req.send("origin")
           })
           .on_challenged_request(|_req, response| {
               // This code is executed when a request is challenged: it receives the
               // client request (with the DataDome enriched headers, for logging) and
               // the challenge response, and returns the response to send to the client.
               Ok::<_, Error>(response)
           })
           .handle_request(req)
   }

   on_allowed_request is required - it's expected to call the origin server.
   handle_request only exists once it has been called, so forgetting it is a compile error.
   The module never calls your origin itself, the call must be defined here
   on_challenged_request is optional; without it the challenge response is returned untouched.

3. Declare the backends and stores in your fastly.toml, so that fastly compute publish creates them on first deployment:

   TOML

   [setup.backends.datadome]
     address = "api-fastly.datadome.co"
     description = "DataDome Protection API"
     port = 443
   
   [setup.backends.origin]
     address = "www.example.com"   # the service to protect
     description = "Origin backend"
     port = 443
   
   [setup.secret_stores.datadome]
     description = "Secrets for DataDome Bot protection"
     [setup.secret_stores.datadome.entries.datadome_server_side_key]
       description = "Server side key available in the DataDome dashboard"
   
   [setup.config_stores.datadome]
     description = "Optional configuration for DataDome Bot protection"

   On an existing service, create and link the resources yourself instead:

   • a datadome backend towards api-fastly.datadome.co:443
   • a datadome Secret Store holding your server-side key under datadome_server_side_key
   • optionally a datadome Config Store.

4. Deploy:

   Shell

   fastly compute publish

5. Lower the timeouts of the datadome backend: they are the timeout of the call to the DataDome API, and a new Fastly backend waits up to 1 s to connect and 15 s for the first byte. See How do I change the timeout value?

Congrats! 🎉 Your traffic is now protected by DataDome Bot Protection.

Configuration

The module reads its configuration from two Fastly stores linked to the service. Both are named datadome by default, and every key starts with the datadome_ prefix.

• The Secret Store holds the server-side key.
• The Config Store holds every other setting. It may also hold the server-side key, which is used when the Secret Store isn't linked or has no entry.

Each store is optional on its own: without a Config Store every setting keeps its default, without a Secret Store the key is read from the Config Store. If the key is found in neither, the module logs an error and lets the traffic through unprotected.

Settings

Changes to a Secret Store or Config Store are live within seconds and don't require a new service version.

There is no timeout setting: the timeout of the call to the DataDome API is the one of the datadome backend (see How do I change the timeout value?).

URL matching

Patterns are matched against host + path (for example www.example.com/products/1.html), without the query string. The path is used exactly as received, percent-encoded.

The default static-asset pattern is:

(?i)\.(avi|avif|bmp|css|eot|flac|flv|gif|gz|ico|jpeg|jpg|js|json|less|map|mka|mkv|mov|mp3|mp4|mpeg|mpg|ogg|ogm|opus|otf|pdf|png|svg|svgz|swf|tif|tiff|ttf|wav|webm|webp|woff|woff2|xml|zip)$

Advanced Configuration

Using your own stores

To read the settings from stores you already own, pick their names and a key prefix through the builder. The prefix replaces datadome_ on every key:

DataDome::new()
    .secret_store_name("my_secrets")   // holds `s1_server_side_key`
    .config_store_name("my_config")    // holds `s1_url_pattern_exclusion`, ...
    .key_prefix("s1_")
    .on_allowed_request(|req| req.send("origin"))
    .handle_request(req)

Providing the server-side key from your code

If you don't want a store for the key, pass it to the builder. A key given this way always takes precedence: the Secret Store is never read, a datadome_server_side_key entry in the Config Store is ignored, and the Config Store is still read, optionally, for the other settings:

//Minimal default configuration
DataDome::new()
    .server_side_key("YOUR_SERVER_SIDE_KEY")   // e.g. env!("DATADOME_SERVER_SIDE_KEY")
    .on_allowed_request(|req| req.send("origin"))
    .handle_request(req)

Other configuration must be provided using a Configuration Store.

Enable GraphQL support

Set datadome_enable_graphql_support to true in the Config Store.

Once enabled, POST requests targeting a GraphQL endpoints with content-type: application/json will be analyzed to extract GraphQL operation name and type.

Multiple endpoints can be configured using defining the datadome_graphql_endpoint setting.

Send custom fields

Use request_metadata to send your own values to the DataDome API, such as a user or product ID. It takes a list of payload key and value pairs. A value is one of:

• a fixed string: "premium".into()
• a header of the client request: DataDome::header("x-user-id")
• a closure receiving the client request and returning an Option<String>: DataDome::from_fn(|req| ...)

use datadome_fastly_compute::{DataDome, MetadataField};

DataDome::new()
    .request_metadata([
        ("UserID", DataDome::header("x-user-id")),
        ("ProductID", DataDome::header("x-product-id")),
        ("CustomFieldString1", "premium".into()),
        (
            "CustomFieldInteger1",
            DataDome::from_fn(|req| {
                let value = req.get_header("x-cart-size")?.to_str().ok()?;
                value.parse::<i64>().ok().map(|n| n.to_string())
            }),
        ),
    ])
    .on_allowed_request(|req| req.send("origin"))
    .handle_request(req)

• Your values have priority: they override the value the module collects for the same field.

Logging

The request handed to both hooks already carries the x-datadome-* headers returned by the DataDome API (the x-datadome-request-headers list), whether the request ends up allowed or challenged. The challenge response handed to on_challenged_request carries the x-datadome-headers list, and so does the response of an allowed request once your on_allowed_request returns it.

No header is added when DataDome could not analyse the request (excluded URL, configuration error, timeout or error of the API call), nor when the API answer carries no valid verdict: the request is then forwarded to on_allowed_request untouched.

fn log_headers(prefix: &str, req: &Request) { 
    for name in req.get_header_names().filter(|name| name.as_str().starts_with("x-datadome"))   {
        println!("{prefix} {}: {}", name, req.get_header_str(name).unwrap_or(""));
    }
}

DataDome::new()
    .on_allowed_request(|req| {
        log_headers("allowed", &req);
        req.send("origin")
    })
    .on_challenged_request(|req, response| {
        log_headers("challenged", &req);
        Ok::<_, Error>(response)
    })
    .handle_request(req)

FAQ

How do I change the timeout value?

The timeout of the call to the DataDome API is the one of the datadome backend, configured in the Fastly service (Advanced options of the host): the Fastly Rust SDK has no per-request timeout. A new backend waits up to 1 s to connect and 15 s for the first byte, so lower both, for example to 300 ms:

fastly backend update --service-id <SERVICE_ID> --version <VERSION> \
  --name datadome --connect-timeout 300 --first-byte-timeout 300

Then activate the new service version. When the timeout expires, the module logs a DataDome:Timeout: message and forwards the request to the origin.

How do I test or debug the service?

Check the logs of your Compute service in the Fastly dashboard, or tail them with fastly log-tail --service-id <id>. The module reports configuration problems with a DataDome:Configuration: prefix, timeouts of the DataDome API call with a DataDome:Timeout: prefix, and any other failure of that call with a DataDome:Error: prefix. In every case the request is forwarded to the origin unprotected, except for an invalid regular expression, where only that setting falls back to its default.

• Neither store is linked to the service:

  DataDome:Configuration:Secret Store 'datadome' or Config Store 'datadome' must be linked to this service

• The server-side key is missing from both stores:

  DataDome:Configuration:'datadome_server_side_key' is missing from Secret Store and Config Store

• A regular expression setting is invalid (here the custom exclusion; the static-asset and encoded-character settings keep their default instead):

  DataDome:Configuration:'datadome_url_pattern_exclusion' is not a valid regex, ignored: <regex error>

• The DataDome API did not answer within the timeouts of the datadome backend (connection, first byte or DNS resolution): the error is logged with the DataDome:Timeout: prefix.

• The datadome backend does not exist in the service, or its name is invalid: the error is logged with the DataDome:Error: prefix. Check the backend name, or set datadome_datadome_backend_name.

• The origin backend does not exist in the service: the request fails with Fastly's Requested backend named 'origin' does not exist error. Check the backend name used in your on_allowed_request hook: the module never calls your origin itself.