refactor: centralize runtime feature flag bindings (#2142)

This commit is contained in:
Carlos Florêncio
2026-08-02 15:36:21 +01:00
committed by GitHub
parent 443e9c89cc
commit e077658a61
29 changed files with 1495 additions and 506 deletions
+32
View File
@@ -5,6 +5,9 @@ vi.mock("@/lib/config", () => ({
}));
import { getRuntimeDebugModeAction } from "./features";
import { getFeatureFlagsAction } from "./features";
import { defaultFeatureFlags } from "@/lib/state/slices/features/types";
import type { FeatureFlags } from "@/lib/state/slices/features/types";
type FetchInput = Parameters<typeof fetch>[0];
type FetchInit = Parameters<typeof fetch>[1];
@@ -27,6 +30,35 @@ function jsonResponse(body: unknown): Response {
});
}
function flagsWith(value: boolean): FeatureFlags {
return Object.fromEntries(
Object.keys(defaultFeatureFlags).map((name) => [name, value]),
) as FeatureFlags;
}
describe("getFeatureFlagsAction", () => {
it("normalizes declared backend flags and ignores unknown keys", async () => {
fetchSpy.mockResolvedValueOnce(jsonResponse({ ...flagsWith(true), unknown: true }));
await expect(getFeatureFlagsAction()).resolves.toEqual(flagsWith(true));
});
it("fails closed for missing and non-boolean backend values", async () => {
fetchSpy.mockResolvedValueOnce(jsonResponse({ office: "true", appStatusBar: true }));
await expect(getFeatureFlagsAction()).resolves.toEqual({
...flagsWith(false),
appStatusBar: true,
});
});
it("falls back to all-off defaults when the backend is unavailable", async () => {
fetchSpy.mockResolvedValueOnce(new Response("nope", { status: 503 }));
await expect(getFeatureFlagsAction()).resolves.toEqual(flagsWith(false));
});
});
describe("getRuntimeDebugModeAction", () => {
it("returns true when the effective debug runtime flag is enabled", async () => {
fetchSpy.mockResolvedValueOnce(
+6 -7
View File
@@ -1,8 +1,7 @@
"use server";
import { getBackendConfig } from "@/lib/config";
import { defaultFeaturesState } from "@/lib/state/slices/features/features-slice";
import type { FeatureFlags } from "@/lib/state/slices/features/types";
import { defaultFeatureFlags, type FeatureFlags } from "@/lib/state/slices/features/types";
import type { RuntimeFlagsResponse } from "@/lib/types/runtime-flags";
const { apiBaseUrl } = getBackendConfig();
@@ -12,15 +11,15 @@ const { apiBaseUrl } = getBackendConfig();
// store. Falls back to defaults (all-off) when the backend is unreachable,
// so a dev-server restart doesn't crash page rendering.
//
// Parsing is type-driven via `defaultFeaturesState.features`: every key
// declared on FeatureFlags is read from the response and Boolean-coerced;
// missing or non-bool values fall through to the default. Adding a flag
// is therefore one entry in FeatureFlags + the default — no edit here.
// Parsing is type-driven via `defaultFeatureFlags`: every declared key is read
// from the response and only actual booleans are accepted; missing or
// non-boolean values remain all-off. Adding a flag is therefore one entry in
// the declaration — no edit here.
//
// See docs/decisions/0007-runtime-feature-flags.md.
export async function getFeatureFlagsAction(): Promise<FeatureFlags> {
const url = `${apiBaseUrl}/api/v1/features`;
const defaults = defaultFeaturesState.features;
const defaults: FeatureFlags = { ...defaultFeatureFlags };
try {
const response = await fetch(url, { cache: "no-store" });
if (!response.ok) {
@@ -1,23 +0,0 @@
import { expect, type Page } from "@playwright/test";
import type { PrAssetCapture } from "../../helpers/pr-asset-capture";
export async function assertUnreadDividerSetting(
page: Page,
prCapture: PrAssetCapture,
projectName: string,
): Promise<void> {
await page.goto("/settings/system/feature-toggles");
const unreadDivider = page.getByTestId("feature-toggle-features.unreadDivider");
await expect(unreadDivider).toBeVisible();
await expect(unreadDivider.getByText("Unread divider", { exact: true })).toBeVisible();
await expect(unreadDivider.getByRole("switch", { name: "Toggle Unread divider" })).toBeChecked();
await expect(unreadDivider).toContainText("Source: Default");
await expect(unreadDivider).toContainText("Requires restart");
await unreadDivider.scrollIntoViewIfNeeded();
await prCapture.screenshot(`unread-divider-setting-${projectName}`, {
caption: `Unread divider feature toggle (${projectName})`,
fullPage: true,
});
}
@@ -0,0 +1,24 @@
import { readFile } from "node:fs/promises";
import { resolve } from "node:path";
import { describe, expect, it } from "vitest";
import { defaultFeatureFlags } from "./types";
const backendConfigPath = resolve(process.cwd(), "../backend/internal/common/config/config.go");
function backendFeatureKeys(source: string): string[] {
const structBody = source.match(/type FeaturesConfig struct \{([\s\S]*?)\n\}/)?.[1];
if (!structBody) {
throw new Error("FeaturesConfig declaration not found in backend config");
}
return Array.from(structBody.matchAll(/json:"([^",]+)(?:,[^"]*)?"/g), (match) => match[1]).sort();
}
describe("feature flag repository contract", () => {
it("keeps frontend defaults equal to backend FeaturesConfig JSON keys", async () => {
const backendConfig = await readFile(backendConfigPath, "utf8");
expect(Object.keys(defaultFeatureFlags).sort()).toEqual(backendFeatureKeys(backendConfig));
});
});
@@ -2,7 +2,8 @@ import { describe, expect, it } from "vitest";
import { create } from "zustand";
import { immer } from "zustand/middleware/immer";
import { createFeaturesSlice, defaultFeaturesState } from "./features-slice";
import type { FeaturesSlice } from "./types";
import { defaultFeatureFlags } from "./types";
import type { FeatureFlags, FeaturesSlice } from "./types";
function makeStore() {
return create<FeaturesSlice>()(
@@ -11,6 +12,12 @@ function makeStore() {
);
}
function flagsWith(value: boolean): FeatureFlags {
return Object.fromEntries(
Object.keys(defaultFeatureFlags).map((name) => [name, value]),
) as FeatureFlags;
}
describe("features slice", () => {
// Production-safety invariant: every flag must be false out of the box.
// If this test starts failing because a new flag was added defaulting to
@@ -20,33 +27,14 @@ describe("features slice", () => {
for (const [name, value] of Object.entries(defaultFeaturesState.features)) {
expect(value, `default of features.${name}`).toBe(false);
}
expect(store.getState().features.office).toBe(false);
expect(defaultFeaturesState.features).toHaveProperty("appStatusBar", false);
expect(defaultFeaturesState.features).toHaveProperty("auth", false);
expect(defaultFeaturesState.features).toHaveProperty("claudeBackgroundPromptHandoff", false);
expect(store.getState().features).toEqual(flagsWith(false));
});
it("setFeatures replaces the whole flag map", () => {
const store = makeStore();
store.getState().setFeatures({
office: true,
appStatusBar: true,
auth: true,
claudeBackgroundPromptHandoff: true,
});
expect(store.getState().features.office).toBe(true);
expect(store.getState().features.appStatusBar).toBe(true);
expect(store.getState().features.auth).toBe(true);
expect(store.getState().features.claudeBackgroundPromptHandoff).toBe(true);
store.getState().setFeatures({
office: false,
appStatusBar: false,
auth: false,
claudeBackgroundPromptHandoff: false,
});
expect(store.getState().features.office).toBe(false);
expect(store.getState().features.appStatusBar).toBe(false);
expect(store.getState().features.auth).toBe(false);
expect(store.getState().features.claudeBackgroundPromptHandoff).toBe(false);
store.getState().setFeatures(flagsWith(true));
expect(store.getState().features).toEqual(flagsWith(true));
store.getState().setFeatures(flagsWith(false));
expect(store.getState().features).toEqual(flagsWith(false));
});
});
@@ -1,16 +1,8 @@
import type { StateCreator } from "zustand";
import type { FeaturesSlice, FeaturesSliceState } from "./types";
import { defaultFeatureFlags, type FeaturesSlice, type FeaturesSliceState } from "./types";
export const defaultFeaturesState: FeaturesSliceState = {
// All flags default to false. Production releases ship every flag off
// until the deployment opts in via env var (e.g. KANDEV_FEATURES_OFFICE).
// The SSR layer overwrites this with whatever the backend reports.
features: {
office: false,
appStatusBar: false,
auth: false,
claudeBackgroundPromptHandoff: false,
},
features: { ...defaultFeatureFlags },
};
type ImmerSet = Parameters<
+15 -9
View File
@@ -1,17 +1,23 @@
// Runtime feature-flag state. The shape mirrors the backend's
// /api/v1/features response (FeaturesConfig in
// apps/backend/internal/common/config/config.go). Every flag is a boolean,
// keyed by feature name. New flags are additive — keep this shape stable.
// apps/backend/internal/common/config/config.go). New flags are additive:
// declare the all-off default once and derive the names and state from it.
// See docs/decisions/0007-runtime-feature-flags.md.
export type FeatureFlags = {
office: boolean;
appStatusBar: boolean;
auth: boolean;
claudeBackgroundPromptHandoff: boolean;
};
export const defaultFeatureFlags = {
// New release toggles start disabled in every frontend state. The SSR layer
// overwrites this with the backend's effective values after startup.
office: false,
appStatusBar: false,
auth: false,
claudeBackgroundPromptHandoff: false,
} as const;
export type FeatureName = keyof FeatureFlags;
export type FeatureName = keyof typeof defaultFeatureFlags;
export type FeatureFlags = {
[K in FeatureName]: boolean;
};
export type FeaturesSliceState = {
features: FeatureFlags;