Boolean Middleware Checks — Feature Flag Control for Checkout API Routes

A feature flag on an e-commerce checkout path has one job before all others: make reversal faster and less risky than deployment. Put a boolean decision in middleware, evaluate it once per request from a local snapshot, attach the result and snapshot revision to request context, and emit bounded telemetry around the AI agent loop. Do not call a remote flag service from the route's hot path.

TL;DR: treat is_enabled as a cached control input, not an authorization rule and not a network dependency. Disabled should skip the agent and preserve the established checkout path; enabled should enter the agent path under an explicit latency and cost budget. A rollback changes the snapshot, while request-level consistency prevents a request from switching behavior halfway through.

This is the operational constraint that changes the design: checkout must remain available while the experimental agent is being disabled. Fast rollback is useless if the flag lookup can stall the same route it is meant to protect.

How should Express middleware check a boolean feature flag?

The tempting implementation asks a flag provider for is_enabled inside every request and branches on the returned boolean. The boolean is simple. Its failure semantics are not. A timeout, stale cache, malformed update, process restart, or mid-request configuration change can turn that one branch into a second distributed system on the payment path.

Define the contract before choosing machinery. For this checkout scenario, the middleware reads one immutable in-process snapshot and records four pieces of context: the boolean decision, the snapshot revision, the evaluation time, and a low-cardinality reason such as configured, stale_snapshot, or invalid_update. The downstream handler consumes that decision. It does not evaluate the flag again.

The invariant is short.

One request, one decision.

is_enabled is also the wrong place to encode identity or payment authorization. A flag controls exposure to the agent loop; the normal authentication, inventory, fraud, and payment checks still run on whichever path is selected. If a caller can set the flag through a header or query parameter, the caller has gained control of deployment policy. Keep overrides confined to authenticated test environments, and keep them out of production request handling.

The following Go example shows the boundary as a generic middleware contract. Express has the same lifecycle: read a process-local snapshot near the start of the chain, place the decision on request-scoped state, then call the next handler. The important mechanism is independent of framework syntax.

package gating

import (
    "context"
    "net/http"
    "sync/atomic"
    "time"
)

type Snapshot struct {
    Enabled  bool
    Revision string
    LoadedAt time.Time
}

type Decision struct {
    Enabled   bool
    Revision  string
    Evaluated time.Time
    Reason    string
}

type decisionKey struct{}

type Gate struct {
    current atomic.Pointer[Snapshot]
    maxAge  time.Duration
}

func NewGate(initial Snapshot, maxAge time.Duration) *Gate {
    g := &Gate{maxAge: maxAge}
    g.current.Store(&initial)
    return g
}

func (g *Gate) Replace(next Snapshot) {
    copy := next
    g.current.Store(&copy)
}

func (g *Gate) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        now := time.Now()
        snapshot := g.current.Load()
        decision := Decision{Evaluated: now, Reason: "stale_snapshot"}

        if snapshot != nil {
            decision.Revision = snapshot.Revision
            if now.Sub(snapshot.LoadedAt) <= g.maxAge {
                decision.Enabled = snapshot.Enabled
                decision.Reason = "configured"
            }
        }

        ctx := context.WithValue(r.Context(), decisionKey{}, decision)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func FromContext(ctx context.Context) (Decision, bool) {
    decision, ok := ctx.Value(decisionKey{}).(Decision)
    return decision, ok
}

A stale or absent snapshot disables the optional agent here because the established checkout path is the safer fallback. That is a scenario-specific choice, not a universal doctrine. A flag protecting a dangerous operation might instead fail closed by denying the entire operation. Write the fallback beside the SLO and threat model; otherwise false quietly becomes a policy nobody remembers choosing. The trade-off is explicit: local evaluation removes a request-time dependency and gives up instant, globally synchronized decisions.

The incident lesson is in the rollback path

Consider a bounded production scenario without pretending it is a benchmark: the checkout API normally validates the cart and proceeds through its established flow, while an enabled flag adds a three-step agent loop that classifies the request, calls a model, and validates the proposed action. The release can be healthy at deployment time and still exceed its latency budget when model response time or retry volume rises. The operator's first move should be a flag reversal, not a rebuild.

The failure worth designing around is partial rollback. If the route evaluates is_enabled before every agent step, an update can leave a request with step one enabled and step two disabled. State may have been allocated, accounting may be incomplete, and the trace becomes ambiguous. Snapshotting once in middleware prevents this split-brain behavior inside a request. New requests see the new revision; in-flight requests finish under the old decision unless a separate cancellation mechanism is deliberately invoked.

That distinction matters.

A flag reversal stops new exposure, but it does not automatically cancel work already running. The agent loop still needs a request deadline, bounded retries, and idempotent side effects. A rollback runbook should therefore order actions explicitly: disable new entries, observe traffic by decision revision, allow or cancel in-flight work according to the transaction contract, and verify that the established checkout path has recovered. If cancellation can interrupt a payment-side effect, the transaction contract must settle that risk before rollout; a kill switch cannot repair ambiguous external state.

Rollback safety also changes the deploy sequence. Ship the disabled code path first. Confirm that both branches can be observed, enable only for an internal or deterministic cohort if such targeting exists, then expand exposure while watching the guardrail. Remove the old path only after the flag and rollback window are retired through a separate change. A permanent flag is mutable production code with weak review history.

Observe outcomes, not customer data

A useful span around the agent loop records duration and outcome for each step, while a request-level metric compares established and agent paths. Keep dimensions bounded: decision, snapshot revision, step name, result class, and perhaps a coarse traffic cohort. Do not put customer IDs, prompts, cart contents, raw model responses, or arbitrary error messages into metric labels. High-cardinality dimensions damage capacity planning, and sensitive payloads create a larger security problem than the flag solves.

OWASP's logging guidance says logs should capture enough information for security monitoring while excluding data that should not be recorded directly, including access tokens and sensitive personal data. Apply the same discipline to traces. Record identifiers only when the operational need is explicit and access controls, retention, and sanitization match that need.

This is enough to answer the rollback question: after revision r42 changes the decision to false, does agent-path admission approach zero while checkout success and latency return to their objective? The revision is diagnostic context, not a customer dimension. Keep only a small active set, and stop exporting retired revisions after the rollback window.

I use an SLO-shaped review even when the first implementation is small. Define the checkout availability indicator, a latency indicator such as the proportion of requests within the agreed threshold, and an agent cost indicator such as model units per successful agent-assisted checkout. Then set an exposure guardrail from the error budget. Averages are weak here; a slow tail can consume the user-visible latency budget while the mean looks calm.

No invented threshold belongs in a reusable example.

The limits must come from the service's existing SLO, measured baseline, and business tolerance.

Capacity planning follows the same discipline. At a prospective exposure fraction f, estimate agent concurrency as admitted request rate multiplied by observed agent duration and f, then add retry amplification under the documented policy. Test the fallback at expected peak checkout load, because rollback concentrates traffic on that path. The old path is not a fallback if it has lost the capacity to carry production.

The preventative handler path

The handler should make the branch visible without duplicating flag evaluation. This example assumes standardCheckout and agentCheckout enforce the same authentication and transaction invariants. It also makes the absence of middleware an error instead of silently choosing a path.

package checkout

import (
    "net/http"

    "example.invalid/internal/gating"
)

type Handler struct {
    standardCheckout http.Handler
    agentCheckout    http.Handler
}

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    decision, ok := gating.FromContext(r.Context())
    if !ok {
        http.Error(w, "checkout gate unavailable", http.StatusServiceUnavailable)
        return
    }

    recordAdmission(r.Context(), decision.Enabled, decision.Revision, decision.Reason)

    if !decision.Enabled {
        h.standardCheckout.ServeHTTP(w, r)
        return
    }

    h.agentCheckout.ServeHTTP(w, r)
}

The example.invalid domain is reserved for documentation, so the import is intentionally illustrative. In an Express service, the equivalent request-scoped value can live on a typed property or res.locals; the route reads it once and selects the handler. Keep the evaluation adapter behind a narrow interface so its tests can cover enabled, disabled, stale, malformed, and update-race cases without a live control plane.

Test the race. Start a request under revision A, replace the process snapshot with revision B, and assert that the started request retains A while the next request receives B. Add a deadline test proving that the agent loop stops before the checkout request budget is exhausted, and a fallback load test proving that the disabled path can accept the planned peak. These tests protect the mechanism that a demo's happy-path boolean usually hides.

Buy, build, or keep the control local?

The decision is less about checkbox features than operational ownership. A platform team should compare the entire path from configuration change to process snapshot, including audit needs and on-call failure modes.

My default design choice is the last row as an application boundary, regardless of what supplies the snapshot. It contains lock-in and makes failure behavior testable. It does not imply building a whole control plane. Building targeting, audit, distribution, and a management UI is a product commitment; a thin adapter is ordinary risk isolation.

This approach has real limitations. It does not apply unchanged when the decision must reflect globally serialized state, when legal policy requires an immediate hard stop for in-flight work, or when the branch authorizes access. Those cases need a policy or authorization system with explicit consistency guarantees, plus a different failure analysis. Choose a centralized policy decision point when stale local state is unacceptable; choose deployment configuration when changes are rare and deployment-speed reversal meets the objective. Calling either system a feature flag does not make boolean caching safe.

The checkout rule remains blunt: evaluate once, expose the decision in telemetry, and make false preserve the known path. Then practice the reversal. A flag that looks instant in a dashboard but has unmeasured propagation, ambiguous in-flight behavior, or an under-capacity fallback is not a rollback mechanism; it is optimism stored as configuration.

Sources

• https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
• https://www.rfc-editor.org/rfc/rfc2606.html
• https://opentelemetry.io/docs/specs/otel/trace/
• https://sre.google/sre-book/service-level-objectives/