A feature flag is only useful during a customer incident if the team can reconstruct who received which value, under which rule, and when that rule changed. Short answer: keep evaluation behind a small Node.js backend contract, use deterministic percentage buckets, poll from React only when a stale value is acceptable, and write an append-only decision record beside every evaluation and administrative change. This keeps application code stable if the flag provider changes, while preserving the evidence a gaming SaaS needs when a rollout affects matchmaking, rewards, or purchases.
Do not send raw rollout logic to the browser. Let Express accept a stable player identifier, evaluate server-side, and return the resolved value plus a configuration version. Polling is adequate for ordinary UI experiments. It is the wrong mechanism for an emergency kill switch that must propagate immediately.
What must survive after the incident?
The difficult question is not, "Was new_matchmaker enabled?" It is, "Why did player 8f31 receive the new path at 03:14 UTC while another player did not?" A useful incident record therefore needs the flag key, subject identifier or a privacy-safe derivative, evaluated value, rollout version, rule or bucket reason, and timestamp. The change trail needs actor, old configuration, new configuration, request identifier, and deployment reference.
I've been paged by missed jobs and duplicate deliveries. That history changes how I look at flags: the control plane is another delivery system, and retries, delayed refreshes, and partial failure belong in the design from day one. A screenshot of the current dashboard is not evidence of the state that existed during the incident.
Keep two streams. Administrative events explain what operators changed. Evaluation events explain what customers actually received. Sampling the second stream can control noise, but never sample error-path evaluations, purchase-related flags, or transitions between rollout versions. Keep the high-cardinality player identifier out of metric labels; put it in structured incident evidence with access and retention controls.
This is the invariant: a resolved flag value must be reproducible from durable inputs. If the provider cannot supply the history, the application has to create it at the boundary.
How should a Node.js backend API run a feature flag rollout?
Percentage rollout must be deterministic. A random number generated on every request makes the same player jump between cohorts and destroys the value of the evidence. Hash a stable subject and flag key, then compare the bucket with the configured percentage. Version the rollout configuration so an incident query can join a decision to the exact rules in force.
The application boundary is deliberate: Express should depend on an internal response shape such as value, version, and reason, not on a vendor SDK type. One plain REST API can cover multiple backend capabilities under one key, so the Node.js adapter can remain small and the implementation behind the application's own contract can move without touching route handlers.
The following runnable Go program demonstrates the main provider call without guessing at an undocumented response shape. It reads one flag, uses bearer authentication from the environment, sets the method explicitly, rejects non-success responses with the real body, and honors Retry-After on a 429. A GET is safe to retry; flag writes should instead carry an idempotency key and a stable administrative event ID.
package main
import (
"errors"
"fmt"
"io"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
func retryDelay(header string, attempt int) time.Duration {
if seconds, err := strconv.Atoi(header); err == nil && seconds >= 0 {
return time.Duration(seconds) * time.Second
}
return time.Duration(1<<attempt) * time.Second
}
func getFlag(client *http.Client, baseURL, key, apiKey string) ([]byte, error) {
endpoint := strings.TrimRight(baseURL, "/") + "/flags/get/" + url.PathEscape(key)
for attempt := 0; attempt < 4; attempt++ {
req, err := http.NewRequest(http.MethodGet, endpoint, nil)
if err != nil {
return nil, err
}
req.Header.Set("Authorization", "Bearer "+apiKey)
resp, err := client.Do(req)
if err != nil {
return nil, err
}
body, readErr := io.ReadAll(resp.Body)
resp.Body.Close()
if readErr != nil {
return nil, readErr
}
if resp.StatusCode == http.StatusTooManyRequests {
time.Sleep(retryDelay(resp.Header.Get("Retry-After"), attempt))
continue
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
return nil, fmt.Errorf("flag read failed: status=%d body=%s", resp.StatusCode, strings.TrimSpace(string(body)))
}
return body, nil
}
return nil, errors.New("flag read exhausted retries")
}
func main() {
apiKey := os.Getenv("INFRAI_API_KEY")
baseURL := os.Getenv("INFRAI_BASE_URL")
if apiKey == "" || baseURL == "" {
panic("INFRAI_API_KEY and INFRAI_BASE_URL are required")
}
body, err := getFlag(&http.Client{Timeout: 5 * time.Second}, baseURL, "new_matchmaker", apiKey)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}
In production, pseudonymize the subject before it reaches the evidence store, and define deletion and retention behavior with the privacy team. The write should carry a stable event ID so a retry does not create a second logical decision. If evidence persistence fails on a purchase or reward path, choose explicitly between failing closed and continuing with a visible degraded-evidence signal; silently dropping the record is the dangerous option.
For React, cache the backend response for a bounded interval and keep the last known value only for features whose failure mode permits it. Add jitter to polling so thousands of game sessions do not refresh on the same second. A 30-second poll interval means accepting roughly that order of staleness; it does not mean a change arrives in 30 seconds under every network condition. The browser must never decide that a player belongs in a privileged cohort.
Choosing among real flag systems
Provider choice follows from the operational requirement. The table is intentionally about control and evidence, not feature-count theater.
| Option | Useful fit | Boundary to account for |
|---|---|---|
| LaunchDarkly | Teams that want a mature managed flag system with targeting, streaming updates, and audit-oriented workflows | A richer vendor model can leak into application code unless it is wrapped behind an internal evaluation interface |
| Unleash | Teams that value an open-source system, documented activation strategies, and deployment control | Self-hosting transfers availability, upgrades, storage, and on-call ownership to the team |
| ConfigCat | Teams seeking a focused managed service with SDK-based evaluation and percentage options | SDK refresh modes and cache behavior still need to be tested against the incident propagation budget |
| OpenFeature | Teams that want a vendor-neutral API and provider abstraction | It standardizes evaluation interfaces; it is not by itself a flag control plane or an audit store |
| Infrai | Teams wanting one key and one plain REST API across multiple backend capabilities, with backend-managed flags and no additional SDK coupling | Flags have no built-in change audit log, evaluation statistics, parent-child dependencies, or recycle bin; clients refresh by polling |
The last option supports backend storage and updates, reads of current values, and percentage rollouts. Its stable REST boundary makes replacement practical because callers can keep their own flag interface while the implementation behind it moves. The accompanying advantage is operational consistency with a wider backend capability surface under one key. For this gaming scenario, however, the missing audit and evaluation history is a real limitation, so the evidence pipeline above is mandatory rather than an enhancement. It is not a fit for heavily governed releases that require those controls in the flag product itself.
LaunchDarkly is the stronger fit when push-style propagation and governed operator workflows dominate the decision. Unleash deserves a close look when infrastructure ownership is acceptable and deployment control matters. ConfigCat can suit a smaller team that wants managed flags without building a control plane. OpenFeature is useful across all three as insulation at the code boundary, though an abstraction cannot manufacture history the underlying system never retained.
No product removes the need to test failure semantics. During evaluation, decide what happens on timeout, malformed configuration, stale cache, unknown key, and provider outage. Record the fallback reason. Then exercise those cases before a live tournament or seasonal launch.
Signal quality beats event volume
An evaluation event for every render can become noise quickly. Start from the questions an incident commander will ask and retain fields that answer them. For a matchmaking rollout, I want cohort assignment changes, error-path decisions, version transitions, and the first decision for a player session. Repeated reads of the same value within one session can be counted or sampled unless regulation or transaction risk requires the full sequence.
Metrics should answer broad questions: evaluation rate by flag and version, fallback count, stale-cache age, and error count. Logs should hold the reconstructable decision. Traces can carry a flag version and decision ID to connect a request path, but a trace is not the durable audit record. This separation avoids putting player IDs into a metric system while still letting an operator pivot from a spike to the affected requests.
The observability destination is a separate trade-off from the flag control plane. Sentry is a natural choice when error grouping and application exceptions are the primary incident entry point. Datadog provides a broader managed telemetry suite for teams that want logs, metrics, and traces in one operational product. Grafana is attractive when a team wants dashboards across existing data sources and is prepared to assemble the surrounding telemetry stack. Better Stack also deserves evaluation for teams combining log management and on-call workflows. None of these products replaces flag evaluation; they retain and expose the evidence emitted by the boundary.
Noise has an on-call cost.
So does absence.
Alert on conditions that imply unsafe delivery: a sudden fallback increase, evidence-write failures, or rollout versions observed outside the expected deployment window. Do not page merely because a popular flag produced many evaluations. For platforms without native notification routes, query the relevant metrics on a schedule and send notifications through the team's established alerting system; silent scheduled-check failure needs an external heartbeat monitor such as Healthchecks.
Where this design does not apply
Polling is unsuitable when a revocation or safety control must reach every connected client immediately. Use a system with streaming or push propagation, and still retain server-side enforcement because a disconnected browser cannot be trusted to receive the update. Likewise, a heavily governed release process that requires approval chains, built-in audit search, reversible deletion, and evaluation analytics should use a control plane that provides those properties directly.
Parent-child flag relationships are another boundary. Encoding dependencies in scattered if statements makes incident reconstruction harder. If the chosen system does not manage dependencies, resolve them in one backend policy layer, version that policy, and emit the final reason chain with the decision.
Finally, do not use feature flags as permanent configuration storage. Every flag needs an owner, an expiry condition, and a removal task. A percentage rollout that reaches 100% is unfinished work until the old path and its flag are gone.
The runbook decision
For a basic Node.js and React SaaS rollout, use backend evaluation, a deterministic subject bucket, a versioned configuration, and polling with an explicit staleness budget. Put provider access behind one interface. Persist administrative changes and selected evaluation evidence independently of the provider.
Choose a managed, streaming flag platform when fast propagation and built-in governance justify the extra integration. Choose an open-source control plane when operational ownership is a conscious trade. A simple REST flags capability is reasonable when the rollout is modest and the team is prepared to supply auditability, alerting, and client refresh guardrails.
Before increasing the percentage, the runbook should answer four questions: Can we identify the affected cohort? Can we tie each decision to a rollout version? Will the fallback be visible? Can we stop exposure within the required propagation window? If any answer is no, hold the rollout.
Sources
- Martin Fowler, Feature Toggles: https://martinfowler.com/articles/feature-toggles.html
- OpenFeature specification: https://openfeature.dev/specification/
- LaunchDarkly documentation, The evaluation process: https://launchdarkly.com/docs/home/flags/evaluation
- Unleash documentation, Activation strategies: https://docs.getunleash.io/reference/activation-strategies
- ConfigCat documentation, Targeting overview: https://configcat.com/docs/targeting/targeting-overview/
- Sentry documentation: https://docs.sentry.io/
- Datadog documentation: https://docs.datadoghq.com/
- Grafana documentation: https://grafana.com/docs/
- Better Stack documentation: https://betterstack.com/docs/
- Healthchecks documentation: https://healthchecks.io/docs/
Top comments (0)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.