9 releases
0.2.4 | Aug 12, 2024 |
---|---|
0.2.3 | Apr 17, 2024 |
0.2.2 | Mar 2, 2024 |
0.2.1 | Feb 13, 2024 |
0.1.2 | Sep 27, 2023 |
#31 in Configuration
7,182 downloads per month
Used in 2 crates
110KB
2K
SLoC
OpenFeature Rust SDK
OpenFeature is an open standard that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool.
🚀 Quick start
Requirements
This package was built with Rust version 1.70.0
. Earlier versions might work, but is not guaranteed.
Install
Add the following content to the Cargo.toml
file:
open-feature = "0.2.4"
Usage
async fn example() -> Result<(), Error> {
// Acquire an OpenFeature API instance.
// Note the `await` call here because asynchronous lock is used to
// guarantee thread safety.
let mut api = OpenFeature::singleton_mut().await;
// Configure a provider.
// By default [`NoOpProvider`] is used.
api.set_provider(NoOpProvider::default()).await;
// create a client
let client = api.get_client();
// get a bool flag value
let is_feature_enabled = client
.get_bool_value("v2_enabled", None, None)
.unwrap_or(false)
.await;
Ok(())
}
Note that the default NoOpProvider
always returns Err
for any given input.
Extended Example
#[tokio::test]
async fn extended_example() {
// Acquire an OpenFeature API instance.
let mut api = OpenFeature::singleton_mut().await;
// Set the default (unnamed) provider.
api.set_provider(NoOpProvider::default()).await;
// Create an unnamed client.
let client = api.create_client();
// Create an evaluation context.
// It supports types mentioned in the specification.
let evaluation_context = EvaluationContext::default()
.with_targeting_key("Targeting")
.with_custom_field("bool_key", true)
.with_custom_field("int_key", 100)
.with_custom_field("float_key", 3.14)
.with_custom_field("string_key", "Hello".to_string())
.with_custom_field("datetime_key", time::OffsetDateTime::now_utc())
.with_custom_field(
"struct_key",
EvaluationContextFieldValue::Struct(Arc::new(MyStruct::default())),
)
.with_custom_field("another_struct_key", Arc::new(MyStruct::default()))
.with_custom_field(
"yet_another_struct_key",
EvaluationContextFieldValue::new_struct(MyStruct::default()),
);
// This function returns a `Result`.
// You can process it with functions provided by std.
let is_feature_enabled = client
.get_bool_value("SomeFlagEnabled", Some(&evaluation_context), None)
.await
.unwrap_or(false);
if is_feature_enabled {
// Let's get evaluation details.
let _result = client
.get_int_details("key", Some(&evaluation_context), None)
.await;
}
}
Getting a Struct from a Provider
It is possible to extract a struct from the provider. Internally, this SDK defines a type StructValue
to store any structure value. The client.get_struct_value()
functions takes a type parameter T
. It will try to parse StructValue
resolved by the provider to T
, as long as T
implements trait TryFrom<StructValue>
.
You can pass in a type that satisfies this trait bound. When the conversion fails, it returns an Err
with EvaluationReason::TypeMismatch
.
API Reference
See here for the API docs.
🌟 Features
Status | Features | Description |
---|---|---|
✅ | Providers | Integrate with a commercial, open source, or in-house feature management tool. |
✅ | Targeting | Contextually-aware flag evaluation using evaluation context. |
❌ | Hooks | Add functionality to various stages of the flag evaluation life-cycle. |
❌ | Logging | Integrate with popular logging packages. |
✅ | Named clients | Utilize multiple providers in a single application. |
❌ | Eventing | React to state changes in the provider or flag management system. |
✅ | Shutdown | Gracefully clean up a provider during application shutdown. |
❌ | Extending | Extend OpenFeature with custom providers and hooks. |
Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌
Providers
Providers are an abstraction between a flag management system and the OpenFeature SDK. Look here for a complete list of available providers. If the provider you're looking for hasn't been created yet, see the develop a provider section to learn how to build it yourself.
Once you've added a provider as a dependency, it can be registered with OpenFeature like this:
// Set the default feature provider. Please replace the `NoOpProvider` with the one you want.
// If you do not do that, [`NoOpProvider`] will be used by default.
//
// [`NoOpProvider`] always returns `Err` despite any input. You can use functions like
// `unwrap_or()` to specify default values.
//
// If you set a new provider after creating some clients, the existing clients will pick up
// the new provider you just set.
//
// You must `await` it to let the provider's initialization to finish.
let mut api = OpenFeature::singleton_mut().await;
api.set_provider(NoOpProvider::default()).await;
In some situations, it may be beneficial to register multiple providers in the same application. This is possible using named clients, which is covered in more detail below.
Targeting
Sometimes, the value of a flag must consider some dynamic criteria about the application or user, such as the user's location, IP, email address, or the server's location. In OpenFeature, we refer to this as targeting. If the flag management system you're using supports targeting, you can provide the input data using the evaluation context.
// Create a global evaluation context and set it into the API.
// Note that this is optional. By default it uses an empty one.
let mut api = OpenFeature::singleton_mut().await;
api.set_evaluation_context(global_evaluation_context).await;
// Set client level evaluation context.
// It will overwrite the global one for the existing keys.
let mut client = api.create_client();
client.set_evaluation_context(client_evaluation_context);
// Pass evaluation context in evaluation functions.
// This one will overwrite the globla evaluation context and
// the client level one.
client.get_int_value("flag", Some(&evaluation_context), None);
Hooks
Hooks are not yet available in the Rust SDK.
Logging
Logging customization is not yet available in the Rust SDK.
Named clients
Clients can be given a name. A name is a logical identifier that can be used to associate clients with a particular provider. If a name has no associated provider, the global provider is used.
// Create a named provider and bind it.
api.set_named_provider("named", NoOpProvider::default()).await;
// This named client will use the feature provider bound to this name.
let client = api.create_named_client("named");
assert_eq!(client.get_int_value("key", None, None).await.unwrap(), 42);
Eventing
Events are not yet available in the Rust SDK.
Shutdown
The OpenFeature API provides a close function to perform a cleanup of all registered providers. This should only be called when your application is in the process of shutting down.
// This will clean all the registered providers and invoke their `shutdown()` function.
let api = OpenFeature::singleton_mut().await;
api.shutdown();
Extending
Develop a provider
To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency.
This can be a new repository or included in the existing contrib repository available under the OpenFeature organization.
You’ll then need to write the provider by implementing the FeatureProvider
interface exported by the OpenFeature SDK.
Check the source of NoOpProvider
for an example.
Built a new provider? Let us know so we can add it to the docs!
Develop a hook
Hooks are not yet available in the Rust SDK.
⭐️ Support the project
- Give this repo a ⭐️!
- Follow us on social media:
- Twitter: @openfeature
- LinkedIn: OpenFeature
- Join us on Slack
- For more, check out our community page
🤝 Contributing
Interested in contributing? Great, we'd love your help! To get started, take a look at the CONTRIBUTING guide.
Thanks to everyone who has already contributed
Made with contrib.rocks.
Dependencies
~3.5–9.5MB
~91K SLoC