DEV Community

IversonBlake8417
IversonBlake8417

Posted on

Percentage Gating for Node.js Users: A Regional Feature Flag Field Guide

#observability #featureflags #node

Use this decision rule: assign each account a stable bucket, apply separate EU and US percentage controls, and advance a staged release only when the new path's telemetry stays inside limits chosen before launch. The flag selects a path. Metrics decide whether that path deserves more traffic.

Keep those jobs separate.

Control approach Pick it when Main trade-off
Environment value plus deployment Changes are rare and deployment approval is already the control plane Every percentage change becomes a release
Versioned configuration, polled by the backend A small team wants reviewable changes without adding a request-time dependency Polling creates bounded propagation delay
Database record plus local cache Rules depend on trusted account data already in the database Cache freshness must be observable across instances
Dedicated flag control plane Many teams need delegated changes, audit history, and richer targeting The service and its client behavior become another operational dependency

How should a Node.js SaaS backend stage feature flag percentage releases?

Start with the unit of exposure. An account-level capability should hash an immutable account ID. A user-level interface can hash an immutable user ID. Mixing those units makes a nominal 10% release difficult to interpret: one large account may contribute far more requests than hundreds of small accounts, while request-by-request randomness can move the same person between old and new behavior.

Next, derive region from trusted account metadata. Don't accept eu or us from an arbitrary request header and treat it as policy. The request can carry an account ID; the backend can resolve that account to its deployment region, then select the corresponding dial. In words, the path is: authenticated account, trusted region, stable bucket, configured threshold, selected variant, recorded exposure. Six steps. Easy to inspect.

Separate regional controls are useful even when both regions eventually reach 100%. They let operators pause one traffic population while continuing to observe the other, and they prevent a blended global graph from hiding a regional difference. They do not prove causation, though. EU and US traffic can differ by time of day, account mix, request volume, and infrastructure, so compare each new variant with its old variant in the same region before comparing regions with each other.

The percentage is a traffic policy, not an experiment result.

Pick the control plane that matches the team

Environment values are a serious option for a low-change internal feature. They inherit deployment review, rollback, and access control. The catch is that an urgent flag change now waits for the deployment path, and a fleet may briefly run mixed values during a rolling update.

A polled, versioned document fits a modest set of backend flags. Each process keeps the last valid configuration in memory and records the version used for every decision. The poll interval defines how quickly a change reaches the fleet, so track configuration age and instance adoption rather than assuming every process switched together. Validation matters too: reject a document with an unknown region, a duplicate flag name, or a percentage outside 0 through 100 before it becomes active.

A database record is attractive when targeting depends on account fields that already have an owner and schema. It also concentrates audit data. But a local cache changes the operational question from "is the row correct?" to "which configuration version did each process use?" Put the version in logs and exposure metrics. Without that join key, a rollback graph can look mysterious even when every component behaved as configured.

Choose a dedicated control plane when flag volume, delegated ownership, approval workflow, or complex dependencies have become the hard part. It isn't automatically safer. Define what the backend does when configuration is stale or unavailable, keep a conservative last-known value in process, and test that behavior. For a sensitive write path, "old" is often the conservative fallback; for a security fix, it may not be. The feature owner has to decide before rollout day.

Implement stable regional bucketing and useful telemetry

This example uses Node's built-in SHA-256 implementation to map a flag and subject to one of 10,000 buckets. The percentages below are illustrative configuration, not recommended launch steps. Using 10,000 buckets permits hundredth-of-a-percent resolution, while the comparison remains integer arithmetic.

import { createHash } from "node:crypto";

type Region = "eu" | "us";
type Variant = "old" | "new";

interface RolloutConfig {
  flag: string;
  version: string;
  basisPointsByRegion: Record<Region, number>;
}

interface Exposure {
  flag: string;
  configVersion: string;
  region: Region;
  variant: Variant;
}

function bucket(flag: string, subjectId: string): number {
  const bytes = createHash("sha256")
    .update(`${flag}\u0000${subjectId}`)
    .digest();

  return bytes.readUInt32BE(0) % 10_000;
}

function chooseVariant(
  config: RolloutConfig,
  region: Region,
  subjectId: string,
): Variant {
  const threshold = config.basisPointsByRegion[region];
  if (!Number.isInteger(threshold) || threshold < 0 || threshold > 10_000) {
    throw new RangeError("rollout percentage must be between 0 and 10,000 basis points");
  }

  return bucket(config.flag, subjectId) < threshold ? "new" : "old";
}

const config: RolloutConfig = {
  flag: "search_index_v2",
  version: "cfg-184",
  basisPointsByRegion: { eu: 500, us: 1_000 },
};

const region: Region = "eu";
const variant = chooseVariant(config, region, "account_7f3a");

const exposure: Exposure = {
  flag: config.flag,
  configVersion: config.version,
  region,
  variant,
};
Enter fullscreen mode Exit fullscreen mode

The null separator prevents ambiguous concatenation, and including the flag name gives each flag its own assignment. Do not change the hash input, algorithm, byte order, modulus, or subject identifier midway through a rollout: any one of those changes reshuffles users. If a reshuffle is intentional, treat it as a new assignment version and observe it as such.

For telemetry, count decisions with flag, region, variant, and config_version as attributes. OpenTelemetry defines a counter as a sum whose value increases over time, which fits exposure counts. Record handler duration separately with a histogram, and count outcomes with a low-cardinality status such as success, validation_error, or dependency_error. Never attach raw account or user IDs to metric attributes; those identifiers create unbounded series. Put a pseudonymous subject reference in structured logs when support needs request-level reconstruction, under the same retention and access rules as other customer-linked operational data.

An exposure counter alone cannot tell you whether the release is healthy. Build paired views for old and new within each region: request count, error proportion, and latency distribution, all filtered to the same operation and configuration version. Then annotate every dial change. A graph without the change time answers "what happened?" slowly; a graph with it gives an operator a crisp before and after.

If the SaaS also ships a desktop client, keep native crash collection distinct from Node.js backend failures. Electron's crashReporter handles native process crashes and minidumps; backend metrics describe server behavior. Correlate the two through privacy-reviewed release and request metadata, but don't pretend a server error counter can see a renderer crash.

Test the rollout as a state machine

Test boundaries first: 0 enables nobody, 10,000 enables everybody, the same input stays stable across process restarts, and invalid values are rejected. Add fixtures for several subject IDs so an accidental hashing change fails code review. Those fixtures test compatibility, not statistical quality.

Then test transitions. Run two backend instances on configuration version A, move the source to version B, and verify that dashboards expose the temporary split until both instances report B. Exercise the defined stale-config behavior. Confirm that lowering the percentage removes exactly the subjects above the new threshold, because stable bucketing produces nested cohorts rather than a fresh random sample.

Run a tabletop example before production: version A sends 500 basis points of EU traffic and 1,000 basis points of US traffic to new; version B changes only the EU value to 1,500. One process sees B while another still has A. An EU account in bucket 900 therefore receives new on the first process and old on the second until configuration converges — a temporary loss of stickiness caused by version skew, even though the hash is perfectly deterministic. The test should make that window visible through config_version, verify that the poller eventually converges, and confirm the response chosen for an invalid version. If the config validator receives 10,001 basis points, reject the candidate before activation and retain the last valid document; don't silently clamp it, because the audit record would say one policy while the runtime applied another. This little rehearsal connects configuration, logs, metrics, and user-visible behavior in one trace. It also gives the on-call engineer an exact diagnostic question: "Are both variants coming from one configuration version, or are two valid versions active?" That's far more useful than staring at a blended error graph.

Writes need another layer. A sticky flag ensures the same subject receives the same variant; it does not make a repeated command safe. Any retryable operation behind the new path needs its own idempotency design, such as a domain operation key enforced by durable storage. HTTP semantics call PUT, DELETE, and safe methods idempotent, but application effects still need testing, and POST does not gain idempotency merely because the flag decision is deterministic.

Set promotion and rollback conditions before exposure begins. There is no universal safe error ratio, latency limit, sample floor, or dwell time; acceptable values depend on traffic shape and consequence of failure. The unresolved question should be explicit: what amount of evidence is enough for this operation? A read-only search change and a billing mutation should not share the same gate.

Know where percentage flags stop

Stable bucketing is not suitable when the goal is a statistically powered product experiment. It supplies deterministic allocation, but the analysis still needs an experimental unit, exposure semantics, sample-size reasoning, and controls for interference. Use an experimentation design when the question is "which experience wins?" rather than "can this code safely take more traffic?"

It is also a poor fit for tightly coupled flag graphs, per-request load shedding, or rules that must react instantly to changing system health. A control plane with explicit dependencies is easier to reason about for flag graphs; a rate limiter or load-shedding mechanism belongs in the traffic path. Stick with a deployment-bound value when changes are rare and the deployment system already provides the governance you need.

The concise field rule is this: deterministic assignment controls who sees the code, regional and variant telemetry shows what the code does, and a prewritten gate controls when exposure grows. None can substitute for the others.

References

Top comments (0)