Skip to main content

Configuration

Build a TogglyConfig once at startup, then pass it to TogglyClient::new(config).await. Request-specific identity, claims, headers and entities belong in EvalContext, not in this shared configuration.

Required Options​

app_key identifies the Toggly application. environment defaults to Production; use the exact environment name configured in your application.

Common Options​

Base URL​

base_url is used for entity-schema registration (/sdk/{appKey}/contexts). It does not change the definition endpoint. Leave it at the service default unless configuring an alternative service or a local test fixture.

Definitions URL​

definitions_url controls definition downloads. The client appends /definitions/{appKey}/{environment}, or /definitions-signed/{appKey}/{environment} when signed definitions are enabled. Both URLs default to https://definitions.toggly.io/.

Refresh Interval​

Polling defaults to 300 seconds. refresh_interval(Duration::from_secs(...)) changes that interval. disable_background_refresh(true) disables periodic polling; startup still fetches definitions. enable_live_updates(true) enables WebSocket-driven updates separately. Leave both mechanisms disabled for a deterministic local fixture.

HTTP Timeout​

http_timeout defaults to 10 seconds. A timeout is a transport failure, not evidence that a flag is disabled.

Development Options​

Enable Undefined in Dev​

enable_undefined_in_dev(true) makes undefined flags evaluate to true. The switch is not restricted by the environment name. Keep its default false unless intentionally using this behavior in a development-only configuration.

Disable Background Refresh​

For applications that own their refresh schedule, disable background refresh and call client.refresh().await?. Use a single application-level scheduler, not one refresh per incoming request.

Cache Options​

Cache TTL​

cache_ttl defaults to 60 seconds. It controls decision retention, independently of the definition refresh interval. See Caching before choosing a value.

Maximum Cache Entries​

cache_max_entries defaults to 10,000. The cache attempts capacity eviction; it does not promise least-recently-used or oldest-first eviction.

Metadata Options​

App Version​

app_version labels the application version in telemetry.

Instance Name​

instance_name distinguishes an application instance. It is not the current user's identity.

Environment Variables​

The Rust client does not automatically read TOGGLY_APP_KEY; the application passes it to the builder. Return or handle a missing-variable error without embedding a real key in source.

Full Example​

This complete src/main.rs uses the dependencies from the quick start. The entity schema upload switch is on TogglyConfigBuilder, so this example uses that builder explicitly.

use std::time::Duration;
use toggly::{TogglyClient, TogglyConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = TogglyConfig::builder()
        .app_key(std::env::var("TOGGLY_APP_KEY")?)
        .environment("Production")
        .refresh_interval(Duration::from_secs(300))
        .http_timeout(Duration::from_secs(10))
        .cache_ttl(Duration::from_secs(60))
        .cache_max_entries(10_000)
        .enable_undefined_in_dev(false)
        .disable_entity_context_registration(false)
        .app_version(env!("CARGO_PKG_VERSION"))
        .instance_name("catalog-api")
        .build();

    let client = TogglyClient::new(config).await?;
    println!("Loaded {} definitions", client.feature_keys().await.len());
    client.close().await;
    Ok(())
}

Register local entity mappers and schemas before creating the client if you want startup catalog registration. Schema registration is best-effort; its success does not create flag conditions.

Signed Definitions and Diagnostics​

Enable use_signed_definitions(true) to request signed definitions. allowed_key_ids optionally restricts accepted signing keys. on_error accepts an Arc callback for reported errors; last_error().await exposes the last definition-refresh error and etag().await exposes its current ETag. These are diagnostics, not an evaluated snapshot.

Shutdown​

Stop accepting work, drain application requests, then client.close().await before ending the runtime. Close flushes telemetry best-effort, signals provider shutdown and clears decisions. Dropping a client is not an equivalent awaited telemetry flush. See each adapter's complete example for lifecycle ownership.