Feature-flag service walk-through: rulesets, local evaluation and stable percentage rollouts

Goal

Evaluate flags in every service consistently, change them without a deploy, roll out by percentage without users flipping between variants, and keep evaluation working when the flag service is down.

Prerequisites

A list of environments, the attributes available for targeting (user id, tenant, region, app version), and an agreement that flags expire unless marked operational.

Steps

1. Constraints: evaluation is local and cheap; the same subject gets the same variant in every service; every change is attributable; client-side SDKs must not receive rules that reveal targeting data.
2. Components: a definition store with an admin API; a distributor that serves the full ruleset per environment with a version and an ETag, by polling or streaming; SDKs that cache the ruleset and evaluate locally; a convention for the evaluation context, which the OpenFeature specification describes as ambient information for flag evaluation used for targeting, overrides and fractional evaluation; a change log.
3. Data model: flag(key, env, type, variants[], default_variant, enabled, rules[], version, owner, expires_at); rule(conditions[], variant | rollout{variant: percent}); change(flag, env, author, before, after, at); served as one ruleset(env, version, flags[]) document.
4. Stable rollouts: hash flag_key + subject_key into a bucket from 0 to 9999 and compare with the rollout percentage; the same hash in every SDK keeps a subject in its variant across services and as the percentage grows. Never draw a random number per evaluation.
5. Failure modes: distributor down (SDKs keep the last ruleset in memory and on disk, and fall back to code defaults only on a cold start); version skew between services for seconds after a change (accept it; for decisions that must agree, evaluate once at the edge and pass the result along); browsers or mobile apps receiving the full ruleset (serve pre-evaluated values to untrusted clients); flags that never expire (report evaluations per flag and age); a rule referencing an attribute the context lacks (define the fallthrough explicitly).
6. Measure: ruleset propagation time, evaluations per flag per day (zero means dead), share of evaluations that used defaults, flags past expires_at, changes per day by author.
7. Not first: experiment statistics, a visual rule builder, dependencies between flags, per-request overrides, scheduled changes.

Expected result

A change reaches all services within the propagation bound, no subject flips back and forth during a rollout, and an outage of the flag service leaves every service on its last known ruleset.

Limits and test basis

Proposed design, no measurements. Toggle types and clean-up discipline are in the feature toggles article; this walk-through covers the service and its SDK contract.