feature_flag/lib.rs
1//! # feature-flag
2//!
3//! Server-side feature flag evaluation for async Rust services.
4//!
5//! ## Design rules
6//!
7//! 1. **No external RNG.** Sticky bucketing is a SHA-256 of `(flag_id ‖ subject_id)`
8//! mod 100 — deterministic, no entropy source, no `rand` dep.
9//! 2. **Tokio is assumed.** Hot reload uses `tokio::fs` + an async watcher.
10//! 3. **Cheap clones.** The evaluator is `Arc`-shaped under the hood, so handing
11//! it to many tasks is free.
12//! 4. **Snapshot for tests.** Build a [`FlagSet`] in code, drop it into a
13//! [`FlagEvaluator`], evaluate. No I/O required.
14//!
15//! ## Primitives
16//!
17//! - [`FlagSet`] — declarative collection of flags, deserialised from JSON.
18//! - [`Flag`] — one named flag with default + ordered targeting [`Rule`]s.
19//! - [`Rule`] — a `match_when` [`Predicate`] plus an outcome ([`Variant`] or
20//! percentage rollout).
21//! - [`Predicate`] — small DSL of typed comparisons + `all_of` / `any_of` / `not`.
22//! - [`Subject`] — the entity being evaluated (id + arbitrary attributes).
23//! - [`FlagEvaluator`] — combines a [`FlagSet`] with a sticky-bucketing function.
24//! - [`HotReloader`] — watches a JSON file for changes and atomically swaps the
25//! evaluator's [`FlagSet`].
26//!
27//! ## Composes with
28//!
29//! - **[reliability-toolkit-rs](https://github.com/mizcausevic-dev/reliability-toolkit-rs)** —
30//! wrap a rollout-controlled call in a circuit breaker + retry.
31//! - **[slo-budget-tracker](https://github.com/mizcausevic-dev/slo-budget-tracker)** —
32//! if your SLO is burning, flip the flag to `default_off` from a remote
33//! config push.
34
35#![warn(missing_docs)]
36#![warn(rust_2018_idioms)]
37#![warn(clippy::pedantic)]
38#![allow(clippy::module_name_repetitions)]
39#![allow(clippy::missing_errors_doc)]
40#![allow(clippy::missing_panics_doc)]
41#![allow(clippy::must_use_candidate)]
42#![allow(clippy::cast_possible_truncation)]
43#![allow(clippy::cast_sign_loss)]
44#![allow(clippy::doc_markdown)]
45#![allow(clippy::unnecessary_debug_formatting)]
46
47pub mod error;
48pub mod evaluator;
49pub mod hot_reload;
50pub mod model;
51pub mod predicate;
52pub mod subject;
53
54pub use error::FeatureFlagError;
55pub use evaluator::{Evaluation, FlagEvaluator};
56pub use hot_reload::HotReloader;
57pub use model::{Flag, FlagSet, Rule, Variant};
58pub use predicate::{Comparison, Predicate};
59pub use subject::Subject;