Node.js Feature Flag Rollouts: Stable Bucketing for 10% Notification Releases

When implementing Node.js feature flags for stable bucketing, store the rollout percentage in the flag system but make the release decision in the request path. Use a deterministic hash of an immutable user or account ID to determine the delivery path, ensuring that the same tenant consistently receives notifications. This approach avoids noise from switching cohorts between requests and simplifies the design to a single percentage, a documented hash rule, and an SLO guardrail.

To avoid using a random-number generator on every request, implement a small, deterministic evaluation rule using an immutable identifier. For property management, an account ID is often a better unit than a user ID, as multiple staff members in the same property should not receive different delivery behavior. If intentional user-level variation is needed, document this explicitly.

A Go implementation of this approach uses SHA-256 to create a stable identifier, taking the first eight bytes and mapping them into 10,000 buckets. The percentage rollout is then checked against this bucket. The contract is precise enough to reproduce in a Node.js backend and for offline analysis.

When designing the alerting page for on-call engineers, display the flag key, rollout percentage, region, channel, and cohort, along with a link to the affected delivery attempts. This provides clear context and helps responders understand the release state without reconstructing it.

Thresholds should be set based on cohort-specific error-budget burn comparisons between the new path and the stable path. Split traffic dimensions (such as US and EU tenants) before applying the threshold to account for varying traffic volumes and delivery dependencies. For low-volume slices, implement a minimum sample rule or a longer window to ensure weak evidence does not trigger unnecessary alerts. Finally, define the minimum evidence and error-budget action before enabling the feature flag.