Add user-scoped feature flags

Allow named feature previews to be enabled for selected WCA users while global production flags remain off. Use the gate for solve history so user 8184 can access the preview without exposing it to other users.

Author: coder13

.env.example

@@ -8,6 +8,8 @@ ROOM_RECONNECT_GRACE_MS=60000
 GRAND_PRIX_ENABLED=false
 # Friend System routes remain disabled through the #188 launch gate.
 SOCIAL_FEATURES_ENABLED=false
+# Comma-separated WCA user IDs approved for the solve-history preview.
+FEATURE_SOLVE_HISTORY_USER_IDS=
 # Manual Compose commands use this tag. scripts/deploy.sh overrides it with
 # the full deployed commit SHA.
 APP_IMAGE_TAG=local

compose.yml

@@ -7,6 +7,7 @@ x-app-environment: &app-environment
   ROOM_RECONNECT_GRACE_MS: ${ROOM_RECONNECT_GRACE_MS:-60000}
   GRAND_PRIX_ENABLED: ${GRAND_PRIX_ENABLED:-false}
   SOCIAL_FEATURES_ENABLED: ${SOCIAL_FEATURES_ENABLED:-false}
+  FEATURE_SOLVE_HISTORY_USER_IDS: ${FEATURE_SOLVE_HISTORY_USER_IDS:-}
   METRICS_ENABLED: ${METRICS_ENABLED:-true}
   METRICS_RETENTION_DAYS: ${METRICS_RETENTION_DAYS:-90}
   METRICS_HASH_SECRET: ${METRICS_HASH_SECRET:-}

docs/development.md

@@ -81,6 +81,11 @@ environment variables. Important groups are documented in `.env.example`:
 - CORS origins and metric retention; and
 - production TLS and backup paths.
 
+An otherwise disabled feature that opts into user targeting can be scoped to selected WCA users with
+`FEATURE_<FLAG>_USER_IDS`, a comma-separated allowlist of numeric user IDs.
+For example, `FEATURE_SOLVE_HISTORY_USER_IDS=8184` enables the solve-history
+preview only for that signed-in user while its global production flag remains off.
+
 `.env.example` is a template, not a file automatically sourced by host Node
 processes. Compose only passes variables referenced in its service environment;
 export any additional server override explicitly or add it to the relevant

server/api/solveHistory.js

@@ -1,6 +1,6 @@
 const express = require('express');
 
-const { isFeatureEnabled } = require('../features');
+const { isFeatureEnabledForUser } = require('../features');
 const { recordSolveHistoryRequest } = require('../metrics');
 const { query } = require('../postgres');
 const { stableId } = require('../postgres/dualWrite');
@@ -111,7 +111,7 @@ const solveResponse = (row) => ({
 });
 
 const createSolveHistoryRouter = ({
-  enabled = isFeatureEnabled('solveHistory'),
+  enabled = (user) => isFeatureEnabledForUser('solveHistory', user && user.id),
   postgresQuery = query,
   recordMetric = recordSolveHistoryRequest,
   now = () => Date.now(),
@@ -123,7 +123,8 @@ const createSolveHistoryRouter = ({
     let outcome = 'error';
     let count = 0;
     try {
-      if (!enabled) {
+      const featureEnabled = typeof enabled === 'function' ? enabled(req.user) : enabled;
+      if (!featureEnabled) {
         outcome = 'feature_disabled';
         return res.status(404).json({
           code: 'feature_disabled',

server/api/solveHistory.test.js

@@ -27,6 +27,21 @@ describe('solve history API', () => {
     expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ code: 'feature_disabled' }));
   });
 
+  it('allows only the configured user when the feature is user-scoped', async () => {
+    const postgresQuery = jest.fn().mockResolvedValue({ rows: [] });
+    const enabled = (user) => user && user.id === 8184;
+
+    const allowed = response();
+    await handlerFor({ enabled, postgresQuery })({ query: {}, user: { id: 8184 } }, allowed);
+    expect(postgresQuery).toHaveBeenCalledTimes(1);
+    expect(allowed.json).toHaveBeenCalledWith({ solves: [], nextCursor: null });
+
+    const blocked = response();
+    await handlerFor({ enabled, postgresQuery })({ query: {}, user: { id: 8185 } }, blocked);
+    expect(blocked.status).toHaveBeenCalledWith(404);
+    expect(postgresQuery).toHaveBeenCalledTimes(1);
+  });
+
   it('returns only session-linked authorized PostgreSQL history with stable cursors', async () => {
     const postgresQuery = jest.fn().mockResolvedValue({ rows: [{
       solve_id: '4d8ce8c4-8910-47e9-b39f-79e1280c1e3a',

server/features.js

@@ -5,7 +5,33 @@ const FEATURES = Object.freeze({
 
 const isFeatureEnabled = (feature) => FEATURES[feature] === true;
 
+const userFeatureEnvironmentKey = (feature) => `FEATURE_${feature
+  .replace(/([a-z])([A-Z])/g, '$1_$2')
+  .toUpperCase()}_USER_IDS`;
+
+const parseUserIds = (value) => new Set((value || '')
+  .split(',')
+  .map((userId) => userId.trim())
+  .filter((userId) => /^[1-9]\d*$/.test(userId)));
+
+const USER_FEATURES = Object.freeze(Object.fromEntries(
+  Object.keys(FEATURES).map((feature) => [
+    feature,
+    parseUserIds(process.env[userFeatureEnvironmentKey(feature)]),
+  ]),
+));
+
+const isFeatureEnabledForUser = (feature, userId) => (
+  isFeatureEnabled(feature)
+  || (typeof userId === 'number' && Number.isSafeInteger(userId) && userId > 0
+    ? USER_FEATURES[feature]?.has(String(userId)) === true
+    : typeof userId === 'string' && /^[1-9]\d*$/.test(userId)
+      ? USER_FEATURES[feature]?.has(userId) === true
+      : false)
+);
+
 module.exports = {
   FEATURES,
   isFeatureEnabled,
+  isFeatureEnabledForUser,
 };

server/features.test.js

@@ -1,31 +1,68 @@
 /* eslint-env jest */
 
 const originalNodeEnv = process.env.NODE_ENV;
+const originalSolveHistoryUserIds = process.env.FEATURE_SOLVE_HISTORY_USER_IDS;
+const originalFriendsUserIds = process.env.FEATURE_FRIENDS_USER_IDS;
 
-const loadFeatures = (nodeEnv) => {
+const loadFeatures = ({ nodeEnv, solveHistoryUserIds, friendsUserIds }) => {
   jest.resetModules();
   process.env.NODE_ENV = nodeEnv;
+  if (solveHistoryUserIds === undefined) {
+    delete process.env.FEATURE_SOLVE_HISTORY_USER_IDS;
+  } else {
+    process.env.FEATURE_SOLVE_HISTORY_USER_IDS = solveHistoryUserIds;
+  }
+  if (friendsUserIds === undefined) {
+    delete process.env.FEATURE_FRIENDS_USER_IDS;
+  } else {
+    process.env.FEATURE_FRIENDS_USER_IDS = friendsUserIds;
+  }
   // eslint-disable-next-line global-require
   return require('./features');
 };
 
 afterEach(() => {
   process.env.NODE_ENV = originalNodeEnv;
+  if (originalSolveHistoryUserIds === undefined) {
+    delete process.env.FEATURE_SOLVE_HISTORY_USER_IDS;
+  } else {
+    process.env.FEATURE_SOLVE_HISTORY_USER_IDS = originalSolveHistoryUserIds;
+  }
+  if (originalFriendsUserIds === undefined) {
+    delete process.env.FEATURE_FRIENDS_USER_IDS;
+  } else {
+    process.env.FEATURE_FRIENDS_USER_IDS = originalFriendsUserIds;
+  }
 });
 
 describe('feature flags', () => {
   it('keeps friends out of production', () => {
-    expect(loadFeatures('production').isFeatureEnabled('friends')).toBe(false);
+    expect(loadFeatures({ nodeEnv: 'production' }).isFeatureEnabled('friends')).toBe(false);
   });
 
   it('keeps friends available to local development', () => {
-    expect(loadFeatures('development').isFeatureEnabled('friends')).toBe(true);
+    expect(loadFeatures({ nodeEnv: 'development' }).isFeatureEnabled('friends')).toBe(true);
   });
 
   it('keeps solve history development-only', () => {
-    expect(loadFeatures('development').isFeatureEnabled('solveHistory')).toBe(true);
-    expect(loadFeatures('dev').isFeatureEnabled('solveHistory')).toBe(true);
-    expect(loadFeatures('production').isFeatureEnabled('solveHistory')).toBe(false);
-    expect(loadFeatures('prod').isFeatureEnabled('solveHistory')).toBe(false);
+    expect(loadFeatures({ nodeEnv: 'development' }).isFeatureEnabled('solveHistory')).toBe(true);
+    expect(loadFeatures({ nodeEnv: 'dev' }).isFeatureEnabled('solveHistory')).toBe(true);
+    expect(loadFeatures({ nodeEnv: 'production' }).isFeatureEnabled('solveHistory')).toBe(false);
+    expect(loadFeatures({ nodeEnv: 'prod' }).isFeatureEnabled('solveHistory')).toBe(false);
+  });
+
+  it('can enable a disabled feature for selected WCA users', () => {
+    const features = loadFeatures({
+      nodeEnv: 'prod',
+      solveHistoryUserIds: '8184, 42, invalid, 0',
+      friendsUserIds: '8184',
+    });
+
+    expect(features.isFeatureEnabled('solveHistory')).toBe(false);
+    expect(features.isFeatureEnabledForUser('solveHistory', 8184)).toBe(true);
+    expect(features.isFeatureEnabledForUser('solveHistory', '42')).toBe(true);
+    expect(features.isFeatureEnabledForUser('solveHistory', 8185)).toBe(false);
+    expect(features.isFeatureEnabledForUser('friends', 8184)).toBe(true);
+    expect(features.isFeatureEnabledForUser('unknown', 8184)).toBe(false);
   });
 });