Feature Flags: Rollout, Kill Switches and Debt

1// Bucket on a STABLE key hashed with the flag name, so the same tenant
2// always gets the same variant, and different flags bucket independently.
3function bucket(flagKey: string, subjectId: string): number {
4  return hash32(`${flagKey}:${subjectId}`) % 100          // 0..99, stable
5}
6 
7function evaluate(flagKey: string, ctx: EvalContext): boolean {
8  const rules = flagCache.get(flagKey)                     // local, refreshed in background
9  if (!rules) {
10    fallbackEvaluations.inc({ flag: flagKey })             // graph this — silent defaults hide outages
11    return SAFE_DEFAULTS[flagKey]                          // provider down != our outage
12  }
13  if (rules.tenantAllowlist?.includes(ctx.tenantId)) return true
14  return bucket(flagKey, ctx.tenantId) < rules.percentage
15}
16 
17// ONE evaluation per request, at the boundary.
18app.use((req, _res, next) => {
19  req.flags = Object.freeze({
20    newPricing: evaluate('new-pricing', { tenantId: req.auth.tenantId }),
21  })
22  // Now on every log line and every metric for this request:
23  req.log = req.log.child({ variant_new_pricing: req.flags.newPricing })
24  next()
25})
26 
27// Downstream code reads the decision; it never re-evaluates.
28const price = req.flags.newPricing ? newEngine.price(cart) : legacyEngine.price(cart)

The frozen req.flags object is the mechanism. A refresh landing halfway through this request changes flagCache and cannot change req.flags, so the request executes exactly one coherent path.