Per-Request Feature Flags in NestJS with a Custom Decorator and Resolution Guard

import { SetMetadata } from '@nestjs/common';

export const FEATURE_FLAG_KEY = Symbol('feature-flag');

export interface FeatureFlagOptions {
  key: string;
  redirectOnDisabled?: boolean;
}

export const RequireFeature = (
  key: string,
  options: Partial<Omit<FeatureFlagOptions, 'key'>> = {},
) => SetMetadata(FEATURE_FLAG_KEY, { key, ...options } as FeatureFlagOptions);

import { Injectable } from '@nestjs/common';
import { createHash } from 'crypto';

export interface FlagContext {
  userId?: string;
  tenantId?: string;
  override?: boolean;
}

interface FlagRule {
  defaultOn: boolean;
  rolloutPercent?: number;
}

@Injectable()
export class FeatureFlagService {
  private readonly rules: Record<string, FlagRule> = {
    'new-checkout': { defaultOn: false, rolloutPercent: 25 },
    'beta-search': { defaultOn: true },
  };

  isEnabled(flag: string, ctx: FlagContext): boolean {
    const rule = this.rules[flag];
    if (!rule) return false;

    if (typeof ctx.override === 'boolean') return ctx.override;

    if (rule.rolloutPercent != null && ctx.userId) {
      return this.bucket(flag, ctx.userId) < rule.rolloutPercent;
    }

    return rule.defaultOn;
  }

  private bucket(flag: string, userId: string): number {
    const digest = createHash('sha256').update(`${flag}:${userId}`).digest();
    return digest.readUInt32BE(0) % 100;
  }
}

import {
  CanActivate,
  ExecutionContext,
  Injectable,
  NotFoundException,
} from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { FEATURE_FLAG_KEY, FeatureFlagOptions } from './feature-flag.decorator';
import { FeatureFlagService, FlagContext } from './feature-flag.service';

@Injectable()
export class FeatureFlagGuard implements CanActivate {
  constructor(
    private readonly reflector: Reflector,
    private readonly flags: FeatureFlagService,
  ) {}

  canActivate(context: ExecutionContext): boolean {
    const meta = this.reflector.getAllAndOverride<FeatureFlagOptions>(
      FEATURE_FLAG_KEY,
      [context.getHandler(), context.getClass()],
    );
    if (!meta) return true;

    const req = context.switchToHttp().getRequest();
    const ctx: FlagContext = {
      userId: req.user?.id,
      tenantId: req.user?.tenantId,
      override: this.parseOverride(req.headers['x-feature-override']),
    };

    if (this.flags.isEnabled(meta.key, ctx)) return true;
    throw new NotFoundException();
  }

  private parseOverride(header?: string): boolean | undefined {
    if (header === 'on') return true;
    if (header === 'off') return false;
    return undefined;
  }
}