210 lines
7.6 KiB
Markdown
210 lines
7.6 KiB
Markdown
# Feature-Flags Engine v2
|
|
|
|
The v2 engine ships in `packages/feature-flags/` and adds targeting
|
|
rules, variants, dependencies, audit-trail, two-tier cache and an
|
|
SSR-hydrated React hook on top of the existing `FeatureFlag` Prisma
|
|
table. Legacy boolean-only callers (`FeatureFlagsService.hasFeatureFlag`)
|
|
keep working unchanged — the migration is additive.
|
|
|
|
## Storage
|
|
|
|
`prisma/schema/featureFlags.prisma` extends `FeatureFlag` with:
|
|
|
|
| Column | Type | Purpose |
|
|
|----------------|-------------|------------------------------------------------------|
|
|
| `rules` | `Json?` | Targeting-rule tree (see below). |
|
|
| `variants` | `Json[]` | Variant array `[{ key, weight?, value? }, ...]`. |
|
|
| `enabledFrom` | `DateTime?` | Lower bound for time-based killswitches. |
|
|
| `enabledUntil` | `DateTime?` | Upper bound for time-based killswitches. |
|
|
| `parentFlagId` | `String?` | Self-reference. Parent must be enabled for child. |
|
|
|
|
The `FeatureFlagAudit` table is append-only — every CRUD / toggle
|
|
writes a row with `actorUserId`, `action`, `oldValue`, `newValue`.
|
|
The app never UPDATEs / DELETEs audit rows; admins can verify
|
|
tamper-resistance by reading the audit log alone.
|
|
|
|
Migration: `prisma/migrations/20260517100000_05_feature_flags_v2/`.
|
|
All new columns nullable / defaulted so existing rows keep evaluating
|
|
through the legacy boolean `enabled` flag.
|
|
|
|
## Rule-tree schema
|
|
|
|
Every node has a `type` discriminator. Composite trees combine leaves
|
|
via AND / OR / NOT. Strict union — adding a new leaf type forces an
|
|
exhaustive evaluator update.
|
|
|
|
### Leaves
|
|
|
|
```jsonc
|
|
// boolean
|
|
{ "type": "boolean", "value": true }
|
|
|
|
// allowlist — OR over tenantIds / userIds / emails
|
|
{ "type": "allowlist",
|
|
"tenantIds": ["tenant_a", "tenant_b"],
|
|
"userIds": ["user_42"],
|
|
"emails": ["alice@example.com"] }
|
|
|
|
// percentage — sticky SHA1(<bucketKey>:<flagName>) % 100 < N
|
|
{ "type": "percentage", "rolloutPercent": 30, "bucketBy": "userId" }
|
|
|
|
// plan-tier — match if ctx.planTier in plans
|
|
{ "type": "plan-tier", "plans": ["pro", "enterprise"] }
|
|
|
|
// role-based — match if ctx.roles intersects roles
|
|
{ "type": "role-based", "roles": ["admin", "beta-tester"] }
|
|
|
|
// time-based — match if now ∈ [enabledFrom, enabledUntil]
|
|
{ "type": "time-based",
|
|
"enabledFrom": "2026-06-01T00:00:00Z",
|
|
"enabledUntil": "2026-12-31T23:59:59Z" }
|
|
```
|
|
|
|
### Composite
|
|
|
|
```jsonc
|
|
// enterprise-tier OR (10% of pro users) — gradual roll-out gated by plan
|
|
{ "type": "composite", "op": "OR",
|
|
"children": [
|
|
{ "type": "plan-tier", "plans": ["enterprise"] },
|
|
{ "type": "composite", "op": "AND",
|
|
"children": [
|
|
{ "type": "plan-tier", "plans": ["pro"] },
|
|
{ "type": "percentage", "rolloutPercent": 10 }
|
|
] } ] }
|
|
```
|
|
|
|
### Sticky percentage rollouts
|
|
|
|
The bucket is `SHA1(<userId>:<flagName>) mod 100`, big-endian over the
|
|
first 4 bytes of the digest. A user that sees a feature at 30%
|
|
rollout will keep seeing it until the percentage drops below their
|
|
bucket — no per-request flipping. Switch `bucketBy: "tenantId"` to
|
|
make whole organisations sticky as one unit.
|
|
|
|
Distribution: tested over 10 000 random user-ids at 30% rollout
|
|
the observed share stays within ±5%.
|
|
|
|
## evaluateFlag
|
|
|
|
```ts
|
|
import { evaluateFlagForRequest } from "~/utils/services/.server/featureFlagsRequest.server";
|
|
|
|
const result = await evaluateFlagForRequest("checkout-v2", { request, params });
|
|
// result: { enabled: boolean, variant?: FlagVariant, reason: string }
|
|
if (result.enabled) {
|
|
render(result.variant?.key ?? "default");
|
|
}
|
|
```
|
|
|
|
Reasons (typed union): `flag-not-found`, `disabled`,
|
|
`time-window-future`, `time-window-expired`, `parent-disabled`,
|
|
`parent-not-found`, `no-match`, `matched`. Safe to log; never contains
|
|
PII pulled from the evaluation context.
|
|
|
|
### Dependency resolution
|
|
|
|
If `parentFlagId` is set the parent must be enabled, in-window, and
|
|
match its own targeting rules. Cycles are bounded by `maxDepth = 8`
|
|
and resolve fail-closed to `parent-disabled`.
|
|
|
|
### Variant selection
|
|
|
|
If multiple variants are configured the engine picks one
|
|
deterministically based on `SHA1(<userId>:<flagName>:variant) mod 100`
|
|
scaled to the sum of weights (missing `weight` defaults to 1). Single-
|
|
variant flags return that variant unconditionally.
|
|
|
|
## Eval cache + pub/sub invalidation
|
|
|
|
Cache lives in the shared-store two-tier helper (#39). Key:
|
|
`ff:<flagName>:<hash(ctx)>` where `hash(ctx)` covers
|
|
`(tenantId, userId, email, planTier, roles)`. Default TTL 60 s
|
|
(`FEATURE_FLAGS_CACHE_TTL_SECONDS` overrides).
|
|
|
|
Channel: `feature-flags:invalidate` (under the shared-store namespace).
|
|
Web boot calls `subscribeFeatureFlagCache()` once from
|
|
`cache-bootstrap.server.ts`. On any flag mutation (admin save, CLI
|
|
toggle, Stripe-driven activation) the publisher calls
|
|
`invalidateFlagCache(flagName)`; every replica drops its L1 entirely on
|
|
receipt (cheap — mutations are rare and L1 entries are tiny).
|
|
|
|
To opt out for a single replica (debugging) set
|
|
`CACHE_INVALIDATION_ENABLED=false` — the subscriber is suppressed and
|
|
the L1 entries expire via TTL.
|
|
|
|
## Admin UI
|
|
|
|
Route: `/admin/feature-flags/engine`. Lists every flag with toggle +
|
|
rule-JSON editor + last 50 audit entries. Visual rule-builder
|
|
(tree-render with drag-drop, percentage slider, allowlist autocomplete,
|
|
live affected-count) is a documented follow-up — the JSON editor
|
|
catches structurally-broken trees by running them through `evaluateRule`
|
|
against a probe context before persisting.
|
|
|
|
## Client SDK + SSR hydration
|
|
|
|
```tsx
|
|
import { FeatureFlagProvider, useFeatureFlag } from "@toolctrl/feature-flags/client";
|
|
|
|
// root.tsx loader — pre-evaluate every flag the tree consumes
|
|
export async function loader({ request, params }: Route.LoaderArgs) {
|
|
const flags = await evaluateFlagsForContext(["chat-v2", "ab-onboarding"], { ... });
|
|
return { flags };
|
|
}
|
|
|
|
// root.tsx component — lift the map into context
|
|
export default function Root({ loaderData }: Route.ComponentProps) {
|
|
return (
|
|
<FeatureFlagProvider flags={loaderData.flags}>
|
|
<Outlet />
|
|
</FeatureFlagProvider>
|
|
);
|
|
}
|
|
|
|
// any descendant — read synchronously, no fetch in render
|
|
function Page() {
|
|
const { enabled, variant } = useFeatureFlag("chat-v2");
|
|
if (!enabled) return null;
|
|
return <Chat variant={variant?.key} />;
|
|
}
|
|
```
|
|
|
|
Convenience hooks: `useFeatureFlagEnabled(name): boolean` and
|
|
`useFeatureFlagVariant(name): string | undefined`.
|
|
|
|
Hydration shape:
|
|
|
|
```ts
|
|
type FeatureFlagsHydration = Record<string, { enabled: boolean; variant?; reason: string }>;
|
|
```
|
|
|
|
Missing entries fall back to `{ enabled: false, reason: "flag-not-found" }`
|
|
so a stale client bundle (deployment skew) does not crash the page when
|
|
a new flag is referenced.
|
|
|
|
## CLI
|
|
|
|
```bash
|
|
toolctrl-cli feature-flags list # every flag with state
|
|
toolctrl-cli feature-flags list --enabled=true # filter
|
|
toolctrl-cli feature-flags enable <flag-name>
|
|
toolctrl-cli feature-flags disable <flag-name>
|
|
toolctrl-cli feature-flags set-rules <flag-name> --file=rules.json # or '-' for stdin
|
|
```
|
|
|
|
Every mutation writes an audit row and triggers a pub/sub
|
|
invalidation; no separate cache-clear step.
|
|
|
|
## Follow-ups
|
|
|
|
- **Visual rule-builder UI.** Drag-drop AND/OR/NOT composer, percentage
|
|
slider, allowlist search with debounced Tenant/User lookup, variant-
|
|
JSON Monaco editor. Tracked in the detail-md.
|
|
- **`POST /api/feature-flags/preview-affected`** — backend that
|
|
estimates how many tenants/users a rule change would affect, used by
|
|
the visual builder for live feedback.
|
|
- **Engine kill-switch `FEATURE_FLAGS_USE_LEGACY=true`** — meta-flag to
|
|
bypass v2 entirely during a roll-back window. Skeleton in place
|
|
(the v1 service is still wired); flip-switch wiring is a follow-up.
|