Feature Flags for Backend Services — Beyond the Toggle

interface FeatureFlag {
  key: string;
  enabled: boolean;
  rolloutPercentage: number;  // 0-100
  targetSegments?: string[];
  killSwitch: boolean;
}
 
function isFeatureEnabled(
  flag: FeatureFlag,
  context: { userId: string; segment?: string }
): boolean {
  // Kill switch overrides everything
  if (flag.killSwitch) return false;
  if (!flag.enabled) return false;
 
  // Segment targeting
  if (flag.targetSegments?.length) {
    if (!context.segment || !flag.targetSegments.includes(context.segment)) {
      return false;
    }
  }
 
  // Deterministic percentage rollout (same user always gets same result)
  const hash = murmurhash3(`${flag.key}:${context.userId}`);
  const bucket = (hash % 100) + 1; // 1-100
  return bucket <= flag.rolloutPercentage;
}

// Wrap third-party calls with operational flags
async function processPayment(order: Order): Promise<PaymentResult> {
  const useNewProcessor = isFeatureEnabled(
    flags.get("new_payment_processor"),
    { userId: order.customerId }
  );
 
  if (useNewProcessor) {
    try {
      return await newPaymentProcessor.charge(order);
    } catch (error) {
      // If new processor fails, automatically fall back
      metrics.increment("payment.new_processor.fallback");
      return await legacyPaymentProcessor.charge(order);
    }
  }
 
  return await legacyPaymentProcessor.charge(order);
}
 
// Operational flag for circuit breaking
async function callExternalApi(request: ApiRequest): Promise<ApiResponse> {
  if (flags.get("external_api_circuit_breaker")?.killSwitch) {
    // Return cached/default response when circuit is open
    return getCachedResponse(request) ?? getDefaultResponse(request);
  }
  return await externalApi.call(request);
}

// Test a new recommendation algorithm in production
async function getRecommendations(userId: string): Promise<Product[]> {
  const useNewAlgorithm = isFeatureEnabled(
    flags.get("recommendation_v2"),
    { userId }
  );
 
  const startTime = Date.now();
  let recommendations: Product[];
  let algorithm: string;
 
  if (useNewAlgorithm) {
    recommendations = await newRecommendationEngine.getRecommendations(userId);
    algorithm = "v2";
  } else {
    recommendations = await currentRecommendationEngine.getRecommendations(userId);
    algorithm = "v1";
  }
 
  // Track which algorithm served which user
  metrics.histogram("recommendations.latency", Date.now() - startTime, { algorithm });
  analytics.track("recommendations_served", {
    userId,
    algorithm,
    count: recommendations.length,
    productIds: recommendations.map(r => r.id),
  });
 
  return recommendations;
}

// Flag metadata tracks lifecycle
interface FlagMetadata {
  key: string;
  type: "release" | "operational" | "experiment" | "permission";
  createdBy: string;
  createdAt: Date;
  expiresAt?: Date;        // When should this flag be removed?
  owner: string;           // Who's responsible for cleanup?
  jiraTicket?: string;     // Cleanup ticket
  lastEvaluated?: Date;    // When was this flag last checked?
}
 
// Automated stale flag detection
async function findStaleFlags(): Promise<FlagMetadata[]> {
  const flags = await flagStore.getAllMetadata();
  
  return flags.filter(flag => {
    // Release flags older than 30 days are stale
    if (flag.type === "release") {
      const age = daysSince(flag.createdAt);
      return age > 30 && flag.rolloutPercentage === 100;
    }
    
    // Experiment flags that expired
    if (flag.type === "experiment" && flag.expiresAt) {
      return new Date() > flag.expiresAt;
    }
 
    // Flags never evaluated in 90 days
    if (flag.lastEvaluated) {
      return daysSince(flag.lastEvaluated) > 90;
    }
 
    return false;
  });
}

// Test both paths — flags introduce branching that needs coverage
describe("Payment processing", () => {
  it("processes payment with new processor when flag is enabled", async () => {
    flags.override("new_payment_processor", { enabled: true, rolloutPercentage: 100 });
    const result = await processPayment(mockOrder);
    expect(newProcessor.charge).toHaveBeenCalled();
  });
 
  it("processes payment with legacy processor when flag is disabled", async () => {
    flags.override("new_payment_processor", { enabled: false });
    const result = await processPayment(mockOrder);
    expect(legacyProcessor.charge).toHaveBeenCalled();
  });
 
  it("falls back to legacy when new processor fails", async () => {
    flags.override("new_payment_processor", { enabled: true, rolloutPercentage: 100 });
    newProcessor.charge.mockRejectedValue(new Error("timeout"));
    const result = await processPayment(mockOrder);
    expect(legacyProcessor.charge).toHaveBeenCalled();
  });
});