{"id":20607704,"url":"https://github.com/open-feature/rust-sdk","last_synced_at":"2025-04-05T06:04:59.999Z","repository":{"id":66557684,"uuid":"566087590","full_name":"open-feature/rust-sdk","owner":"open-feature","description":"Rust implementation of the OpenFeature SDK","archived":false,"fork":false,"pushed_at":"2025-03-28T22:07:26.000Z","size":198,"stargazers_count":36,"open_issues_count":9,"forks_count":10,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T05:04:49.214Z","etag":null,"topics":["openfeature","rust","sdk"],"latest_commit_sha":null,"homepage":"https://openfeature.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-feature.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-14T23:59:55.000Z","updated_at":"2025-03-26T20:09:41.000Z","dependencies_parsed_at":"2024-02-18T10:25:19.253Z","dependency_job_id":"1bd256dd-d45c-4ed3-bcd4-642e2d679058","html_url":"https://github.com/open-feature/rust-sdk","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-feature%2Frust-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-feature%2Frust-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-feature%2Frust-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-feature%2Frust-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-feature","download_url":"https://codeload.github.com/open-feature/rust-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294538,"owners_count":20915340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openfeature","rust","sdk"],"created_at":"2024-11-16T10:08:22.370Z","updated_at":"2025-04-05T06:04:59.982Z","avatar_url":"https://github.com/open-feature.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD033 --\u003e\n\u003c!-- x-hide-in-docs-start --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/open-feature/community/0e23508c163a6a1ac8c0ced3e4bd78faafe627c7/assets/logo/horizontal/white/openfeature-horizontal-white.svg\" /\u003e\n    \u003cimg align=\"center\" alt=\"OpenFeature Logo\" src=\"https://raw.githubusercontent.com/open-feature/community/0e23508c163a6a1ac8c0ced3e4bd78faafe627c7/assets/logo/horizontal/black/openfeature-horizontal-black.svg\" /\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003ch2 align=\"center\"\u003eOpenFeature Rust SDK\u003c/h2\u003e\n\n\u003c!-- x-hide-in-docs-end --\u003e\n\u003c!-- The 'github-badges' class is used in the docs --\u003e\n\u003cp align=\"center\" class=\"github-badges\"\u003e\n  \u003ca href=\"https://github.com/open-feature/spec/releases/tag/v0.5.2\"\u003e\n    \u003cimg alt=\"Specification\" src=\"https://img.shields.io/static/v1?label=specification\u0026message=v0.5.2\u0026color=yellow\u0026style=for-the-badge\" /\u003e\n  \u003c/a\u003e\n  \u003c!-- x-release-please-start-version --\u003e\n  \u003ca href=\"https://github.com/open-feature/rust-sdk/releases/tag/v0.2.5\"\u003e\n    \u003cimg alt=\"Release\" src=\"https://img.shields.io/static/v1?label=release\u0026message=v0.2.5\u0026color=blue\u0026style=for-the-badge\" /\u003e\n  \u003c/a\u003e\n  \u003c!-- x-release-please-end --\u003e\n\n  \u003cbr/\u003e\n  \u003c!-- TODO: update this when we have it set up\n  \u003ca href=\"https://bestpractices.coreinfrastructure.org/projects/6601\"\u003e\n    \u003cimg alt=\"CII Best Practices\" src=\"https://bestpractices.coreinfrastructure.org/projects/6601/badge\" /\u003e\n  \u003c/a\u003e\n  --\u003e\n  \u003ca href=\"https://crates.io/crates/open-feature\"\u003e\n    \u003cimg alt=\"Crates.io\" src=\"https://img.shields.io/crates/v/open-feature\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.rust-lang.org/tools/install\"\u003e\n    \u003cimg alt=\"Min rust version\" src=\"https://img.shields.io/badge/rust-%3E=1.70.0-blue.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.repostatus.org/#wip\"\u003e\n    \u003cimg alt=\"Repo status\" src=\"https://www.repostatus.org/badges/latest/wip.svg\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003c!-- x-hide-in-docs-start --\u003e\n\n[OpenFeature](https://openfeature.dev) is an open standard that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool.\n\n\u003c!-- x-hide-in-docs-end --\u003e\n## 🚀 Quick start\n\n### Requirements\n\nThis package was built with Rust version `1.70.0`. Earlier versions might work, but is not guaranteed.\n\n### Install\n\nAdd the following content to the `Cargo.toml` file:\n\n\u003c!-- x-release-please-start-version --\u003e\n```toml\nopen-feature = \"0.2.5\"\n```\n\u003c!-- x-release-please-end --\u003e\n### Usage\n\n```rust\nasync fn example() -\u003e Result\u003c(), Error\u003e {\n    // Acquire an OpenFeature API instance.\n    // Note the `await` call here because asynchronous lock is used to\n    // guarantee thread safety.\n    let mut api = OpenFeature::singleton_mut().await;\n\n    // Configure a provider.\n    // By default [`NoOpProvider`] is used.\n    api.set_provider(NoOpProvider::default()).await;\n\n    // create a client\n    let client = api.get_client();\n\n    // get a bool flag value\n    let is_feature_enabled = client\n        .get_bool_value(\"v2_enabled\", None, None)\n        .unwrap_or(false)\n        .await;\n\n    Ok(())\n}\n```\n\nNote that the default `NoOpProvider` always returns `Err` for any given input.\n\n#### Extended Example\n\n```rust\n#[tokio::test]\nasync fn extended_example() {\n    // Acquire an OpenFeature API instance.\n    let mut api = OpenFeature::singleton_mut().await;\n\n    // Set the default (unnamed) provider.\n    api.set_provider(NoOpProvider::default()).await;\n\n    // Create an unnamed client.\n    let client = api.create_client();\n\n    // Create an evaluation context.\n    // It supports types mentioned in the specification.\n    let evaluation_context = EvaluationContext::default()\n        .with_targeting_key(\"Targeting\")\n        .with_custom_field(\"bool_key\", true)\n        .with_custom_field(\"int_key\", 100)\n        .with_custom_field(\"float_key\", 3.14)\n        .with_custom_field(\"string_key\", \"Hello\".to_string())\n        .with_custom_field(\"datetime_key\", time::OffsetDateTime::now_utc())\n        .with_custom_field(\n            \"struct_key\",\n            EvaluationContextFieldValue::Struct(Arc::new(MyStruct::default())),\n        )\n        .with_custom_field(\"another_struct_key\", Arc::new(MyStruct::default()))\n        .with_custom_field(\n            \"yet_another_struct_key\",\n            EvaluationContextFieldValue::new_struct(MyStruct::default()),\n        );\n\n    // This function returns a `Result`.\n    // You can process it with functions provided by std.\n    let is_feature_enabled = client\n        .get_bool_value(\"SomeFlagEnabled\", Some(\u0026evaluation_context), None)\n        .await\n        .unwrap_or(false);\n\n    if is_feature_enabled {\n        // Let's get evaluation details.\n        let _result = client\n            .get_int_details(\"key\", Some(\u0026evaluation_context), None)\n            .await;\n    }\n}\n```\n\n#### Getting a Struct from a Provider\n\nIt 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\u003cStructValue\u003e`.\n\nYou can pass in a type that satisfies this trait bound. When the conversion fails, it returns an `Err` with `EvaluationReason::TypeMismatch`.\n\n### API Reference\n\nSee [here](https://docs.rs/open-feature/latest/open_feature/index.html) for the API docs.\n\n## 🌟 Features\n\n| Status | Features                        | Description                                                                                                                        |\n| ------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n| ✅      | [Providers](#providers)         | Integrate with a commercial, open source, or in-house feature management tool.                                                     |\n| ✅      | [Targeting](#targeting)         | Contextually-aware flag evaluation using [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context). |\n| ✅      | [Hooks](#hooks)                 | Add functionality to various stages of the flag evaluation life-cycle.                                                             |\n| ✅      | [Logging](#logging)             | Integrate with popular logging packages.                                                                                           |\n| ✅      | [Named clients](#named-clients) | Utilize multiple providers in a single application.                                                                                |\n| ❌      | [Eventing](#eventing)           | React to state changes in the provider or flag management system.                                                                  |\n| ✅      | [Shutdown](#shutdown)           | Gracefully clean up a provider during application shutdown.                                                                        |\n| ✅      | [Extending](#extending)         | Extend OpenFeature with custom providers and hooks.                                                                                |\n\n\u003csub\u003eImplemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌\u003c/sub\u003e\n\n### Providers\n\n[Providers](https://openfeature.dev/docs/reference/concepts/provider) are an abstraction between a flag management system and the OpenFeature SDK.\nLook [here](https://openfeature.dev/ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Provider\u0026instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=Rust) for a complete list of available providers.\nIf the provider you're looking for hasn't been created yet, see the [develop a provider](#develop-a-provider) section to learn how to build it yourself.\n\nOnce you've added a provider as a dependency, it can be registered with OpenFeature like this:\n\n```rust\n// Set the default feature provider. Please replace the `NoOpProvider` with the one you want.\n// If you do not do that, [`NoOpProvider`] will be used by default.\n//\n// [`NoOpProvider`] always returns `Err` despite any input. You can use functions like \n// `unwrap_or()` to specify default values.\n//\n// If you set a new provider after creating some clients, the existing clients will pick up\n// the new provider you just set.\n//\n// You must `await` it to let the provider's initialization to finish.\nlet mut api = OpenFeature::singleton_mut().await;\napi.set_provider(NoOpProvider::default()).await;\n```\n\nIn some situations, it may be beneficial to register multiple providers in the same application.\nThis is possible using [named clients](#named-clients), which is covered in more detail below.\n\n### Targeting\n\nSometimes, 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.\nIn OpenFeature, we refer to this as [targeting](https://openfeature.dev/specification/glossary#targeting).\nIf the flag management system you're using supports targeting, you can provide the input data using the [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context).\n\n```rust\n// Create a global evaluation context and set it into the API.\n// Note that this is optional. By default it uses an empty one.\nlet mut api = OpenFeature::singleton_mut().await;\napi.set_evaluation_context(global_evaluation_context).await;\n\n// Set client level evaluation context.\n// It will overwrite the global one for the existing keys.\nlet mut client = api.create_client();\nclient.set_evaluation_context(client_evaluation_context);\n\n// Pass evaluation context in evaluation functions.\n// This one will overwrite the global evaluation context and \n// the client level one.\nclient.get_int_value(\"flag\", Some(\u0026evaluation_context), None);\n```\n\n### Hooks\n\n[Hooks](https://openfeature.dev/docs/reference/concepts/hooks) allow for custom logic to be added at well-defined points of the flag evaluation life-cycle.\nLook [here](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Hook\u0026instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=Rust) for a complete list of available hooks.\nIf the hook you're looking for hasn't been created yet, see the [develop a hook](#develop-a-hook) section to learn how to build it yourself.\n\nOnce you've added a hook as a dependency, it can be registered at the global, client, or flag invocation level.\n\n```rust\nlet mut api = OpenFeature::singleton_mut().await;\n\n// Set a global hook.\napi.set_hook(MyHook::default()).await;\n\n// Create a client and set a client level hook.\nlet client = api.create_client();\nclient.set_hook(MyHook::default());\n\n// Get a flag value with a hook.\nlet eval = EvaluationOptions::default().with_hook(MyHook::default());\nclient.get_int_value(\"key\", None, Some(\u0026eval)).await;\n```\n\nExample of a hook implementation you can find in [examples/hooks.rs](https://github.com/open-feature/rust-sdk/blob/main/examples/hooks.rs).\n\nTo run the example, execute the following command:\n\n```shell\ncargo run --example hooks\n```\n\n### Logging\n\nNote that in accordance with the OpenFeature specification, the SDK doesn't generally log messages during flag evaluation.\n\n#### Logging hook\n\nThe Rust SDK provides a logging hook that can be used to log messages during flag evaluation.\nThis hook is not enabled by default and must be explicitly set.\n\n```rust\nlet mut api = OpenFeature::singleton_mut().await;\n\nlet client = api.create_client().with_logging_hook(false);\n\n...\n\n// Note: You can include evaluation context to log output.\nlet client = api.create_client().with_logging_hook(true);\n```\n\nBoth **text** and **structured** logging are supported.\nTo enable **structured** logging, enable feature `structured-logging` in your `Cargo.toml`:\n\n```toml\nopen-feature = { version = \"0.2.4\", features = [\"structured-logging\"] }\n```\n\nExample of a logging hook usage you can find in [examples/logging.rs](https://github.com/open-feature/rust-sdk/blob/main/examples/logging.rs).\n\nTo run the example, execute the following command:\n\n```shell\ncargo run --example logging\n```\n\n**Output**:\n\n```text\n[2025-01-10T18:53:11Z DEBUG open_feature::hooks::logging] Before stage: domain=, provider_name=Dummy Provider, flag_key=my_feature, default_value=Some(Bool(false)), evaluation_context=EvaluationContext { targeting_key: None, custom_fields: {} }\n[2025-01-10T18:53:11Z DEBUG open_feature::hooks::logging] After stage: domain=, provider_name=Dummy Provider, flag_key=my_feature, default_value=Some(Bool(false)), reason=None, variant=None, value=Bool(true), evaluation_context=EvaluationContext { targeting_key: None, custom_fields: {} }\n```\n\nor with structured logging:\n\n```shell\ncargo run --example logging --features structured-logging\n```\n\n**Output**:\n\n```jsonl\n{\"default_value\":\"Some(Bool(false))\",\"domain\":\"\",\"evaluation_context\":\"EvaluationContext { targeting_key: None, custom_fields: {} }\",\"flag_key\":\"my_feature\",\"level\":\"DEBUG\",\"message\":\"Before stage\",\"provider_name\":\"No-op Provider\",\"target\":\"open_feature\",\"timestamp\":1736537120828}\n{\"default_value\":\"Some(Bool(false))\",\"domain\":\"\",\"error_message\":\"Some(\\\"No-op provider is never ready\\\")\",\"evaluation_context\":\"EvaluationContext { targeting_key: None, custom_fields: {} }\",\"file\":\"src/hooks/logging.rs\",\"flag_key\":\"my_feature\",\"level\":\"ERROR\",\"line\":162,\"message\":\"Error stage\",\"module\":\"open_feature::hooks::logging::structured\",\"provider_name\":\"No-op Provider\",\"target\":\"open_feature\",\"timestamp\":1736537120828}\n```\n\n### Named clients\n\nClients can be given a name.\nA name is a logical identifier that can be used to associate clients with a particular provider.\nIf a name has no associated provider, the global provider is used.\n\n```rust\n// Create a named provider and bind it.\napi.set_named_provider(\"named\", NoOpProvider::default()).await;\n\n// This named client will use the feature provider bound to this name.\nlet client = api.create_named_client(\"named\");\n\nassert_eq!(client.get_int_value(\"key\", None, None).await.unwrap(), 42);\n```\n### Eventing\n\nEvents are not yet available in the Rust SDK.\n\n\u003c!-- TOOD: Uncomment it when we support events\nEvents allow you to react to state changes in the provider or underlying flag management system, such as flag definition changes, provider readiness, or error conditions.\nInitialization events (`PROVIDER_READY` on success, `PROVIDER_ERROR` on failure) are dispatched for every provider.\nSome providers support additional events, such as `PROVIDER_CONFIGURATION_CHANGED`.\n\nPlease refer to the documentation of the provider you're using to see what events are supported.\n--\u003e\n\n\u003c!-- TODO: code example of a PROVIDER_CONFIGURATION_CHANGED event for the client and a PROVIDER_STALE event for the API --\u003e\n\n### Shutdown\n\nThe OpenFeature API provides a close function to perform a cleanup of all registered providers.\nThis should only be called when your application is in the process of shutting down.\n\n```rust\n// This will clean all the registered providers and invoke their `shutdown()` function.\nlet api = OpenFeature::singleton_mut().await;\napi.shutdown();\n```\n\n## Extending\n\n### Develop a provider\n\nTo develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency.\nThis can be a new repository or included in [the existing contrib repository](https://github.com/open-feature/rust-sdk-contrib) available under the OpenFeature organization.\nYou’ll then need to write the provider by implementing the `FeatureProvider` interface exported by the OpenFeature SDK.\n\nCheck the source of [`NoOpProvider`](https://github.com/open-feature/rust-sdk/blob/main/src/provider/no_op_provider.rs) for an example.\n\n\u003e Built a new provider? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=\u0026labels=provider\u0026projects=\u0026template=document-provider.yaml\u0026title=%5BProvider%5D%3A+) so we can add it to the docs!\n\n### Develop a hook\n\nTo develop a hook, you need to create a new project and include the OpenFeature SDK as a dependency.\nThis can be a new repository or included in [the existing contrib repository](https://github.com/open-feature/rust-sdk-contrib) available under the OpenFeature organization.\nImplement your own hook by conforming to the `Hook interface`.\nTo satisfy the interface, all methods (`before`/`after`/`finally`/`error`) need to be defined.\n\n```rust\nuse open_feature::{\n    EvaluationContext, EvaluationDetails, EvaluationError,\n    Hook, HookContext, HookHints, Value,\n};\n\nstruct MyHook;\n\n#[async_trait::async_trait]\nimpl Hook for MyHook {\n    async fn before\u003c'a\u003e(\n        \u0026self,\n        context: \u0026HookContext\u003c'a\u003e,\n        hints: Option\u003c\u0026'a HookHints\u003e,\n    ) -\u003e Result\u003cOption\u003cEvaluationContext\u003e, EvaluationError\u003e {\n        todo!()\n    }\n\n    async fn after\u003c'a\u003e(\n        \u0026self,\n        context: \u0026HookContext\u003c'a\u003e,\n        details: \u0026EvaluationDetails\u003cValue\u003e,\n        hints: Option\u003c\u0026'a HookHints\u003e,\n    ) -\u003e Result\u003c(), EvaluationError\u003e {\n        todo!()\n    }\n\n    async fn error\u003c'a\u003e(\n        \u0026self,\n        context: \u0026HookContext\u003c'a\u003e,\n        error: \u0026EvaluationError,\n        hints: Option\u003c\u0026'a HookHints\u003e,\n    ) {\n        todo!()\n    }\n\n    async fn finally\u003c'a\u003e(\n        \u0026self,\n        context: \u0026HookContext\u003c'a\u003e,\n        detaild: \u0026EvaluationDetails\u003cValue\u003e,\n        hints: Option\u003c\u0026'a HookHints\u003e,\n    ) {\n        todo!()\n    }\n}\n```\n\n\u003e Built a new hook? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=\u0026labels=hook\u0026projects=\u0026template=document-hook.yaml\u0026title=%5BHook%5D%3A+) so we can add it to the docs!\n\n\u003c!-- x-hide-in-docs-start --\u003e\n## ⭐️ Support the project\n\n- Give this repo a ⭐️!\n- Follow us on social media:\n  - Twitter: [@openfeature](https://twitter.com/openfeature)\n  - LinkedIn: [OpenFeature](https://www.linkedin.com/company/openfeature/)\n- Join us on [Slack](https://cloud-native.slack.com/archives/C0344AANLA1)\n- For more, check out our [community page](https://openfeature.dev/community/)\n\n## 🤝 Contributing\n\nInterested in contributing? Great, we'd love your help! To get started, take a look at the [CONTRIBUTING](CONTRIBUTING.md) guide.\n\n### Thanks to everyone who has already contributed\n\n\u003ca href=\"https://github.com/open-feature/rust-sdk/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=open-feature/rust-sdk\" alt=\"Pictures of the folks who have contributed to the project\" /\u003e\n\u003c/a\u003e\n\n\nMade with [contrib.rocks](https://contrib.rocks).\n\u003c!-- x-hide-in-docs-end --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-feature%2Frust-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-feature%2Frust-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-feature%2Frust-sdk/lists"}