Repository files navigation

Unleash is a private, secure, and scalablefeature management platform built to reduce the risk of releasing new features and accelerate software development. This Rust SDK is designed to help you integrate with Unleash and evaluate feature flags in Rust programs.

You can use this client withUnleash Enterprise orUnleash Open Source.

The client is written using async rust. For communicating with the Unleash APIsurf or reqwest support is built in, or any async HTTP client can be provided bythe user if they implement the thin trait used to abstract over the actualclient.

Examples with async-std (feature 'surf-client') and tokio (feature'reqwest-client') are in the examples/ in the source tree. See the API docs formore feature information.

To use it in a sync program, run an async executor andblock_on() the relevantcalls. As the client specification requires sending background metrics to theAPI, you will need to arrange to call thepoll_for_updates method from athread as demonstrated inexamples/theads.rs

The unleash defined strategies are included, to support custom strategiesuse theClientBuilder and call thestrategy method to register your customstrategy memoization function.

Thecrate documentation should be consulted for more detail.

The easiest way to get started with theClient is using theClientBuilder. A simple example is provided:

let config =EnvironmentConfig::from_env()?;let client = client::ClientBuilder::default().interval(500).into_client::<UserFeatures, reqwest::Client>(&config.api_url,&config.app_name,&config.instance_id,        config.secret,)?;client.register().await?;

The values required for theinto_client method are described as follows (in order, as seen above):

• api_url - The server URL to fetch toggles from.
• app_name - The name of your application.
• instance_id - A unique ID, ideally per run. A runtime generated UUID would be a sensible choice here.
• authorization - An Unleash client secret, if set this will be passed as the authorization header.

While the above code shows the usage of theEnvironmentConfig, this isn't required and is provided as a convenient way of reading a data from the system environment variables.

Note that if you do use theEnvironmentConfig as a way of accessing the system variables, you'll need to ensure that all the environment variables marked as required in the above table are set, or a panic will be raised.

The ClientBuilder also has a few builder methods for setting properties which are assumed to have good defaults and generally do not require changing. If you do need to alter these properties you can invoke the following methods on the builder (as seen above with the interval).

Core Unleash API features work, with Rust 1.60 or above. The MSRV for this project is weakly enforced: when a hard dependency raises its version, so will the minimum version tested against, but if older rust versions work for a user, that is not prevented.time in particular is known to enforce a 6-month compiler age, so regular increases with the minimum version tested against are expected.

Unimplemented Unleash specified features:

• local serialised copy of toggles to survive restarts without network traffic.

Please note that this project is released with a Contributor Code of Conduct. Byparticipating in this project you agree to abide by its terms.

PR's on Github as normal please. Cargo test to run the test suite, rustfmt codebefore submitting. To run the functional test suite you need an Unleash API toexecute against.

For instance, one way:

docker-compose up -d

Visithttp://localhost:4242/ and log in with admin + unleash4all, then createa new Backend API token athttp://localhost:4242/admin/api/create-token for useradmin, type Client.

Then run the test suite:

UNLEASH_API_URL=http://127.0.0.1:4242/api \  UNLEASH_APP_NAME=fred UNLEASH_INSTANCE_ID=test \  UNLEASH_CLIENT_SECRET="<tokenvalue>" \  cargotest --features functional  -- --nocapture

or similar. The functional test suite looks for a manually setup set offeatures. E.g. log into the Unleash UI on port 4242 and create a feature calleddefault.