Deep dive into consistent hashing, percentage rollouts, variant distribution, and evaluation internals
Last updated November 14, 2026
Advanced Evaluation
This guide covers the internals of Flaggr's evaluation engine — how consistent hashing works, how variants are distributed, and how to design robust rollout strategies.
Evaluation Pipeline
Every flag evaluation follows this sequence:
Disabled Check
If the flag is disabled, return defaultValue with reason DISABLED. No further evaluation occurs.
Identity Overrides
If an override lists the context's targetingKey, return the override's value with reason OVERRIDE. Overrides are checked from the highest priority down.
Prerequisites, Mutual Exclusion and Experiments
On flaggr.dev only. A prerequisite flag that doesn't return its expected value gives defaultValue with reason PREREQUISITE_FAILED. A flag blocked by its mutual exclusion group gives defaultValue with reason MUTUAL_EXCLUSION. A running experiment on the flag assigns its variant (reason EXPERIMENT) when the context has a targetingKey. The data plane at api.flaggr.dev skips this step.
Targeting Rules
Rules are evaluated top-to-bottom. The first rule whose conditions match wins. It returns the rule's value (the flag's defaultValue when the rule has none), labelled with the rule's variant if it names one, with reason TARGETING_MATCH.
Rollout Check
If a matching rule has rolloutPercentage (a whole number from 0 to 100), the user's hash determines inclusion. If excluded, evaluation continues to the next rule. A rule without one, or with null (how the data plane writes an unset percentage in /api/flags/export and its streams), serves every user it matches. The @flaggr/sdk 0.4.0 script-tag bundle evaluating locally skips a rule whose percentage is null instead, which it meets only in a bootstrap built from the data plane's flags (it can't stream from api.flaggr.dev); 0.5.0 serves it.
Variant Selection
If the flag has variants with weights, consistent hashing selects one. Returns with reason VARIANT.
Default Value
If nothing matched, return defaultValue with reason DEFAULT.
Consistent Hashing
Flaggr buckets users with a 32-bit string hash of the targetingKey. flaggr.dev, the data plane at api.flaggr.dev and @flaggr/evaluator from 0.3.0 use the same hash, so the same user always gets the same result for the same flag. @flaggr/evaluator 0.2.0 hashes differently and ignores rollout percentages and identity overrides, so evaluating locally with it can give a user a different result.
How It Works
// A targeting rule's rollout percentage
bucket = hash(flagKey + ":rollout:" + targetingKey) % 100 // 0-99
included = bucket < rolloutPercentage
// Variant weights
bucket = hash(flagKey + targetingKey) % 100 // 0-99
The hash multiplies by 31 and adds each Unicode code point (((h << 5) - h) + c), wrapping to 32 bits, and takes the absolute value:
function hashString(str: string): number {
let hash = 0
for (const c of str) {
hash = (hash * 31 + c.codePointAt(0)!) | 0 // wrap to a 32-bit integer
}
return Math.abs(hash)
}Properties
- Deterministic: Same input always produces the same output
- Uniform: Buckets 0-99 are evenly distributed across users
- Stable: Changing the rollout percentage from 10% to 20% includes the original 10% plus 10% more — no users are removed
- Independent: Each flag has its own hash space (different flags, different assignments), and a rule's rollout bucket is hashed apart from the variant bucket
Without targetingKey in the evaluation context, a rule with a rollout percentage below 100 never includes the user, and weighted variants, identity overrides and experiments don't apply. The @flaggr/sdk 0.4.0 script-tag bundle evaluating locally is the exception for rollouts: it puts every context without a targetingKey in the same bucket, so such a rule includes all of them or none (0.5.0 leaves them out). Rules without a rollout percentage still match on their conditions; otherwise the user gets the flag's default value.
Percentage Rollouts
Basic Rollout
A 25% rollout to all users:
{
"targeting": [
{
"id": "gradual",
"conditions": [
{ "property": "targetingKey", "operator": "not_equals", "value": "__flaggr_rollout_match_all__" }
],
"rolloutPercentage": 25,
"value": true
}
]
}The condition above matches every user, with or without a targetingKey: it's the console's Everyone, which rollout plans use too. A rule with no conditions matches everyone as well on flaggr.dev and in @flaggr/sdk local evaluation from 0.5.0, but a data plane from before Flaggr 0.5.0 and local evaluation before 0.5.0 match it to nobody, so the condition is the form that works on every version.
Targeted Rollout
25% of enterprise users only:
{
"targeting": [
{
"id": "enterprise-canary",
"conditions": [
{ "property": "plan", "operator": "equals", "value": "enterprise" }
],
"rolloutPercentage": 25,
"value": true
}
]
}Progressive Rollout Strategy
Internal Dogfood (1%)
Deploy to internal team members first. Use a targeting rule matching @yourcompany.com emails.
Canary (5%)
Expand to a small percentage of real users. Monitor error rates and latency.
Early Access (25%)
Increase the rollout percentage. Check business metrics and user feedback.
General Availability (100%)
Remove the rollout percentage to serve all users. Clean up the feature flag once stable.
Variant Distribution
For A/B testing and multi-way experiments, use variants with weights:
{
"variants": [
{ "name": "control", "value": "classic-checkout", "weight": 50 },
{ "name": "treatment-a", "value": "new-checkout", "weight": 30 },
{ "name": "treatment-b", "value": "express-checkout", "weight": 20 }
]
}Selection Algorithm
bucket = hash(flagKey + targetingKey) % 100 // e.g., 73
Variant ranges:
control: 0-49 (50%)
treatment-a: 50-79 (30%)
treatment-b: 80-99 (20%)
73 falls in treatment-a → user gets "new-checkout"
Weights are cumulative. The algorithm iterates through variants, accumulating weights until the hash bucket is covered.
Variant weights are whole numbers from 0 to 100 (the API refuses others with 400) and should sum to 100. If they sum to less, users whose bucket is past the last weight get the first variant. If they sum to more, the variants at the end of the list get less than their weight, or none.
Combining Variants with Targeting
Force specific users into specific variants:
{
"targeting": [
{
"id": "force-enterprise-control",
"conditions": [
{ "property": "plan", "operator": "equals", "value": "enterprise" }
],
"value": "classic",
"variant": "control"
}
],
"variants": [
{ "name": "control", "value": "classic", "weight": 50 },
{ "name": "treatment", "value": "new", "weight": 50 }
]
}Enterprise users always get classic, reported as variant control. Everyone else is split 50/50. A rule serves its value (or the flag's default value without one); variant only names the result, so give the rule the variant's value too. The console's Return Variant and MCP add_targeting_rule with variant do that for you.
Evaluation Reasons
Every evaluation returns a reason field explaining how the value was determined:
| Reason | Description | Typical Cause |
|---|---|---|
DISABLED | Flag is disabled | enabled: false |
OVERRIDE | An identity override applied | The targetingKey is listed in an override |
PREREQUISITE_FAILED | A prerequisite flag didn't return its expected value (flaggr.dev only) | Prerequisite disabled or targeted differently |
MUTUAL_EXCLUSION | Blocked by its mutual exclusion group (flaggr.dev only) | Another flag in the group is on |
EXPERIMENT | A running experiment assigned the variant (flaggr.dev only) | Experiment running on the flag |
TARGETING_MATCH | A targeting rule matched | Conditions satisfied (and inside the rule's rollout percentage) |
VARIANT | Selected via variant weights | Hash-based assignment |
DEFAULT | No match, default value used | No rules matched |
NOT_FOUND | Flag doesn't exist (FLAG_NOT_FOUND on api.flaggr.dev) | Typo in flag key, wrong service |
ERROR | Evaluation error | Invalid context, storage failure |
CACHED | Served from cache | Cache TTL still valid |
STATIC | Static/hardcoded value | File provider or bootstrap |
Debug Information
The evaluation API returns timing data in the _debug field:
{
"flagKey": "checkout-v2",
"value": true,
"reason": "TARGETING_MATCH",
"_debug": {
"timings": {
"rateLimit": 2,
"validation": 1,
"cacheGet": 0.5,
"evaluate": 3,
"total": 12
},
"cacheHit": false,
"totalMs": 12
}
}Use this to diagnose slow evaluations. Typical healthy values:
- Cache hit: total under 5ms
- Cache miss: total under 50ms
Type Safety
Flaggr enforces type matching between flags and evaluations:
| Flag Type | Allowed Default Values | Example |
|---|---|---|
boolean | true, false | useBooleanFlag('dark-mode', false) |
string | Any string | useStringFlag('theme', 'light') |
number | Any number | useNumberFlag('max-items', 10) |
object | JSON object | useObjectFlag('config', {}) |
If the evaluated value doesn't match the expected type, the SDK returns the default value with reason ERROR.
Related
- Targeting Rules — Condition operators and rule structure
- Provider Architecture — Local vs remote evaluation
- REST API Reference — Evaluation endpoint details