Skip to main content

Rust SDK

A feature flag lets you choose between application behaviors without changing the deployed code. Toggly's Rust client downloads an application's definitions and evaluates flags locally using the context you provide.

Quick reference

Use the Rust cheat sheet (PDF) beside these guides. The Toggly Samples catalog contains complete applications and flag setup recipes for reference.

Package Architecture​

CratePurpose
togglyClient, configuration, evaluation, entity mapping and telemetry
toggly-actixActix middleware and extractors
toggly-axumAxum layers, extractors and state wrapper
toggly-axum08Axum 0.8 layers, extractors and state wrapper
toggly-rocketRocket initialization fairing and request guard
toggly-macrosOptional function gates and feature-key enums

Install only the adapter used by your application.

Requirements​

Use Rust 1.88 or later and a Tokio runtime. The native adapter guides declare their supported host dependencies: Actix, Axum and Rocket.

Framework compatibility​

AdapterDeclared host rangeCurrent tested hostRequired configuration
toggly-axumAxum 0.7Axum 0.7.9Register Arc<TogglyClient> as an Extension
toggly-axum08Axum 0.8Axum 0.8.9Register Arc<TogglyClient> as an Extension
toggly-actixActix-web 4.4 through 4.15Actix-web 4.15.0Register web::Data<TogglyClient>
toggly-rocketRocket 0.5Rocket 0.5.1Attach the fairing or manage one client

toggly-axum and toggly-axum08 are separate crates because Axum 0.7 and 0.8 use incompatible dependency types. Keep the package and import matching your host major. The adapters intentionally map evaluation errors to false in their convenience feature helpers; use direct client access when the host must handle the SDK error explicitly.

Installation​

For a standalone application, add these dependencies to Cargo.toml:

[dependencies]
toggly = "0.6"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Quick Start​

Create a Toggly application, select its Production environment, and create new-dashboard with an AlwaysOn condition. Set TOGGLY_APP_KEY in your local shell to that application's SDK key. Environment names and feature keys are case-sensitive. Do not commit the key.

Put this complete example in src/main.rs, then run cargo run:

use toggly::{EvalContext, TogglyClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Prepare known targeting before the first evaluation.
    // In a server, obtain these values from the authenticated request.
    let context = EvalContext::builder()
        .identity("user-123")
        .group("beta-testers")
        .build();

    // Create one client for this application's lifetime.
    let client = TogglyClient::builder()
        .app_key(std::env::var("TOGGLY_APP_KEY")?)
        .environment("Production")
        .build()
        .await?;

    let result = client.is_enabled("new-dashboard", context).await;
    // Close before propagating an evaluation error or leaving the runtime.
    client.close().await;
    println!("New dashboard enabled: {}", result?);
    Ok(())
}

The initial request downloads shared definitions for the app and environment; it does not send the user's evaluation context. is_enabled evaluates locally. There is no separate identity-setting call to perform at startup. A missing flag returns false with the default configuration. A missing app key or failed initial definition fetch returns an initialization error; handle that error in your application's startup policy.

Change the condition to AlwaysOff, save it, and run the program again: the output becomes false. A running server receives definition updates through refresh configuration; decision caching also affects when an evaluation changes.

Features​

The SDK supports asynchronous evaluation, shared clients, in-memory definition and decision caches, polling, optional live updates, built-in filters, entity context, and optional usage/business-metric telemetry. Framework helpers expose native integration points, while the application supplies authenticated claims and domain data.

Rust does not expose a variant assignment or evaluated-snapshot export/import API. A caller-supplied telemetry variant label is a correlation label, not an assignment made by the SDK.

Next Steps​