18 KiB
Feature-Flags Engine
Status: in_progress (visual-rule-builder-deferred) Task-ID: #53 Phase: 05 Estimated Effort: 2 Wochen Owner: shipped core engine; admin visual-builder follow-up unassigned
Problem
Ursprünglich hatte die Boilerplate ein rudimentäres packages/feature-flags/-Paket mit nur boolean-Toggles und sehr begrenzter Targeting-Logik. Der Core ist inzwischen umgesetzt (Targeting-Engine, Eval-Cache, CLI, SSR-Hook, Admin-Basisrouten); offen bleibt vor allem der komfortable visuelle Rule-Builder mit Preview-Zählung.
- Gradual-Rollouts neuer Features auf Subsets von Tenants (z.B. 10% Traffic auf neue Chatbot-Version)
- Plan-Tier-Gating (Enterprise-only-Features ohne Hardcoded-Checks)
- A/B-Tests via Multi-Variant-Flags (3 verschiedene Onboarding-Flows messen)
- Killswitches mit Time-Boxing (Feature deaktivieren ab Datum X)
- Dependency-Hierarchien (Sub-Feature nur wenn Parent-Feature aktiv)
Ohne diese Engine bauen Folge-Tasks Hardcoded-Conditionals (if (tenant.planId === "enterprise") { ... }) und produzieren tech-debt. Außerdem blockt das Plugin-System (Phase 06), das Capabilities pro Plugin per Flag aktivieren können soll.
Historisch betroffene Stellen:
packages/feature-flags/src/index.ts— nurisEnabled(name, tenantId)apps/web/app/utils/services/featureFlags.ts— Hardcoded-Mapping aus DB-Row → booleanprisma/schema.prisma—FeatureFlag-Model nur mitname,enabled,tenantId?
Depends on
03-scaling-infrastructure/shared-store-package.md(#37) — Eval-Cache läuft über SharedStore; ohne ihn pro Worker-Instance inkonsistente Eval-Ergebnisse.03-scaling-infrastructure/pubsub-cache-invalidation.md(#39) — Cache-Invalidation bei Flag-Update via Pub/Sub-Channel, sonst hängen Flags bis zur TTL.02-observability/sentry-wiring-api-worker.md(#11) — Eval-Errors müssen in Sentry landen, sonst silent-fail bei Targeting-Bugs.
Blocks
05-business-features/ai-cost-phase-2.md(#55) — Quota-Bypass-Feature-Flag, Soft-Degradation-Modus pro Tenant05-business-features/ai-cost-phase-3.md(#56) — Overage-Aktivierung pro Tenant05-business-features/marketing-funnel-phase-1.md(#78) — Anti-Bot-Layer hinter Flag (Turnstile on/off)06-plugin-system/hooks-lifecycle.md(#61) — Plugin-Capability-Gating07-chatbot/chatbot-mvp.md(#67) — Chatbot-Rollout per Flag pro Tenant08-mobile-cli-storybook-sdk/cli-scaffolding.md(#72) — CLI nutzt Flags für Feature-Detection bei Code-Gen
Approach
Wir bauen die Flag-Engine als first-class Package mit klar getrennten Schichten:
- Storage-Layer — Prisma-Models
FeatureFlag+FeatureFlagAudit(Schema-Erweiterung). - Evaluation-Layer —
evaluateFlag(name, ctx)/getFeatureFlagVariant(name, ctx)inpackages/feature-flags/. - Cache-Layer —
(flagName, contextHash) → resultfür 60s, Invalidation per Pub/Sub-Channelfeature-flags:invalidate. - Admin-UI — visueller Rule-Builder, Variant-Editor, Live-Affected-Count.
- Client-SDK —
useFeatureFlag(name)-Hook mit SSR-Hydration (Flag-Werte werden in Loader vorberechnet und ins Component-Tree gehydrated).
Begründung der Architektur-Wahl:
- Eigene Engine statt LaunchDarkly / Unleash: wir wollen keine externe SaaS-Abhängigkeit für Boilerplate-Käufer und kein zweites Auth-System. Unleash-OSS wäre eine Option, aber dann hätten wir einen weiteren Container — die Engine ist mit 1500 LOC schreibbar und integriert sich nativ in unsere Tenant-/Plan-Layer.
- JSON-Rules-Tree statt DSL: ein composite Tree (
{ op: "AND", children: [...] }) ist im Admin-UI baubar (visueller Rule-Builder) und ohne Parser/Lexer evaluierbar. DSL wäre eleganter, aber unverhältnismäßig für den Scope. - Percentage-Rollout via SHA1(
userId+flagName) % 100: sticky pro User-Flag-Kombi → bei 30%-Rollout sieht ein User das Feature deterministisch entweder immer oder nie. Bei reiner Random-Eval würde der User bei jedem Page-Load anders behandelt — UX-Katastrophe. - Cache via SharedStore mit 60s-TTL: Eval-Hot-Path muss <1ms sein; ohne Cache würde jeder Page-Load DB-Query + Rules-Eval auslösen.
Implementation Steps
- Prisma-Schema-Erweiterung —
FeatureFlag-Model umrules Json,variants Json[],enabledFrom DateTime?,enabledUntil DateTime?,parentFlagId String?erweitern + neues ModelFeatureFlagAudit { id, flagId, actorUserId, action, oldValue Json, newValue Json, createdAt }. Migration generieren.- Files:
prisma/schema.prisma,prisma/migrations/<ts>_feature_flags_v2/migration.sql - Commit:
05/feature-flags: extend prisma model with rules, variants, dependencies, audit
- Files:
- Targeting-Engine in
packages/feature-flags/—evaluateRule(rule, ctx)mit Support für:boolean,allowlist(tenantIds | userIds | emails),percentage(sticky-hash),plan-tier,role-based,time-based,composite(AND/OR/NOT mit Child-Rules). Pure Function, vollständig unit-testbar ohne DB.- Files:
packages/feature-flags/src/targeting/(mehrere Files),packages/feature-flags/src/targeting/targeting.test.ts - Commit:
05/feature-flags: implement targeting rule evaluator
- Files:
evaluateFlag+getFeatureFlagVariantPublic-API — orchestriert Storage-Load, Dependency-Resolution (Parent-Flag-Check), Targeting-Eval, Variant-Auswahl. Strikt typisierte Return-Werte ({ enabled: boolean, variant?: string | Record<string, unknown>, reason: string }).- Files:
packages/feature-flags/src/evaluate.ts,packages/feature-flags/src/evaluate.test.ts - Commit:
05/feature-flags: implement evaluateFlag with dependency resolution
- Files:
- Eval-Cache via SharedStore + Pub/Sub-Invalidation — Cache-Key:
ff:{flagName}:{hash(ctx)}mit 60s-TTL. Beim Flag-Update Pub/Sub-Eventfeature-flags:invalidatemit{ flagName }— alle Subscriber löschen Cache-Entries des Flags.- Files:
packages/feature-flags/src/cache.ts,packages/feature-flags/src/cache.test.ts - Commit:
05/feature-flags: add eval cache with pubsub invalidation
- Files:
- Admin-UI Flag-Liste + Detail-Editor — Routes:
apps/web/app/routes/admin/feature-flags/index.tsx(Liste mit Filter/Search),apps/web/app/routes/admin/feature-flags/$flagName.tsx(Detail). Detail-Editor mit visuellem Rule-Builder (Tree-Render: AND/OR-Knoten + Leaf-Conditions), Percentage-Slider, Allowlist-Search (debounced gegen TenantSearch/UserSearch), Variant-JSON-Editor (Monaco-Editor + Schema-Validation). Live-Affected-Count: bei Targeting-Änderung Backend-CallPOST /api/feature-flags/preview-affectedder gegen Tenant/User-Tabellen die Match-Count berechnet.- Files:
apps/web/app/routes/admin/feature-flags/...(mehrere Files),apps/web/app/components/feature-flags/RuleBuilder.tsx,apps/web/app/components/feature-flags/VariantEditor.tsx - Commit:
05/feature-flags: admin ui with visual rule builder and affected-count preview
- Files:
- Audit-Trail — jede Mutation (Create/Update/Delete) schreibt
FeatureFlagAudit-Row mitactorUserId,oldValue,newValue. Admin-UI zeigt Timeline pro Flag.- Files:
apps/web/app/utils/services/featureFlagAudit.server.ts, Integration in Admin-Action-Handlers - Commit:
05/feature-flags: add audit trail
- Files:
- Client-SDK + SSR-Hook —
useFeatureFlag(name): { enabled, variant }. Inroot.tsx-Loader werden alle vom Route-Tree benötigten Flags vorab evaluiert und über Context an Client gehydrated. Pattern:loaderruftevaluateFlags(['flag-a', 'flag-b'], ctx)→ liefert Map → inLoaderData→ Provider im Component-Tree →useFeatureFlagliest aus Context. Bei Client-Navigation re-fetcht.- Files:
packages/feature-flags/src/client/useFeatureFlag.ts,apps/web/app/root.tsx,apps/web/app/components/feature-flags/FeatureFlagProvider.tsx - Commit:
05/feature-flags: client hook with ssr hydration
- Files:
- Doku —
docs/features/feature-flags.mdmit Targeting-Patterns (Gradual-Rollout, Allowlist-Beta, Killswitch, A/B-Test, Plan-Gating), Code-Beispielen fürevaluateFlagunduseFeatureFlag, Admin-UI-Walkthrough, Cache-Verhalten-Erklärung, Audit-Trail-Lesehinweis.- Files:
docs/features/feature-flags.md - Commit:
05/feature-flags: docs
- Files:
Test Requirements
- Unit-Tests:
targeting.test.ts— alle 7 Rule-Types einzeln, plus 5 composite-Trees (deep-nested AND/OR/NOT-Kombis)percentage-hash.test.ts— sticky-Test: gleicher (userId, flagName) liefert immer gleichen Bucket; Distribution-Test über 10k Sample-IDs liegt bei N% innerhalb ±2%evaluate.test.ts— Dependency-Resolution: Parent disabled → Child immer false; time-based mit enabledFrom/until; Variant-Auswahlcache.test.ts— TTL-Verhalten, Pub/Sub-Invalidation-Listener löscht keysuseFeatureFlag.test.tsx— React-Testing-Library: Provider + Hook + SSR-Hydration-Szenario
- Integration-Tests:
- End-to-End: Flag in DB anlegen →
evaluateFlagin API-Route → erwartetes Ergebnis - Admin-UI: Flag-Update via Action → Audit-Row geschrieben → Cache invalidiert → nächster Eval liefert neuen Wert
- Affected-Count-Preview-Endpoint: gegen Test-Tenants/Users
- End-to-End: Flag in DB anlegen →
- E2E-Tests (Playwright):
- Admin loggt sich ein → navigiert zu
/admin/feature-flags→ öffnet existing Flag → ändert Percentage von 0 auf 50 → speichert → Audit-Trail zeigt Change → User-Session sieht Flag entsprechend - Visual-Rule-Builder: AND-Knoten + 2 Children erstellen, speichern, re-laden, Tree wird korrekt rekonstruiert
- Admin loggt sich ein → navigiert zu
- Coverage-Target: 90% für
packages/feature-flags/, 75% für Admin-UI-Routes - Test-Files: alle neben Source-Files (
<file>.test.ts(x)), E2E unterapps/web/tests/e2e/feature-flags.spec.ts
NICHT als completed markieren bevor alle Tests grün sind.
Acceptance Criteria
- Prisma-Schema-Migration applied;
FeatureFlag+FeatureFlagAuditmit allen neuen Feldern live packages/feature-flags/exportiertevaluateFlag,getFeatureFlagVariant,useFeatureFlag, Type-Definitionen- Alle 7 Targeting-Rule-Types funktional + getestet
- Cache-Layer via SharedStore aktiv, Pub/Sub-Invalidation in <2s wirksam (mess-validated)
- Admin-UI mit Rule-Builder, Percentage-Slider, Allowlist-Search, Variant-Editor, Live-Affected-Count
- Audit-Trail schreibt jede Mutation; UI zeigt Timeline
- Client-SDK
useFeatureFlagmit SSR-Hydration verfügbar - Dependency-Hierarchie funktioniert (Parent disabled → Child immer false)
docs/features/feature-flags.mdmit allen Patterns + Code-Beispielenpnpm lint,pnpm typecheck,pnpm testgrün- Coverage-Gates erfüllt
- Atomic Commits gepushed auf
agent/05-feature-flags - Detail-MD Progress-Log aktualisiert
- PROGRESS.md Status auf
completed
Rollback Strategy
- DB-Migration-Rollback: neue Felder sind alle nullable / Json-nullable / Array →
down-Migration setzt sie nicht zurück (zur Sicherheit). Bei Bedarf Drop-Statement manuell. - Code-Rollback: Revert der Commits in umgekehrter Reihenfolge (Step 8 → 1). Da
evaluateFlag-Signature additive ist (vorher nur boolean, neu mit Variant), reicht Wrapper-FunctionisEnabled(name, ctx) = evaluateFlag(name, ctx).enabledfür Backward-Compat. - Feature-Flag-Killswitch: Meta-Flag
feature-flags-engine-v2selbst — wennfalse, fallback auf alte boolean-only-Logik via Env-ToggleFEATURE_FLAGS_USE_LEGACY=true. Vorhanden für ersten Production-Rollout, kann nach 2 Wochen Stabilität entfernt werden.
Security Notes
- Rule-Builder Injection: Rules-JSON wird vom Admin gebaut, nie von Tenant-Input. Trotzdem im Backend strikt mit Zod-Schema validieren (kein freier String in Operator-Feldern, keine eval-baren Expressions).
- Allowlist-PII: Allowlists können User-Emails enthalten — Admin-UI-Rendering muss Admin-Permission-geschützt sein (already required, aber prüfen).
- Audit-Tamper-Resistance: AuditEvent-Rows append-only; kein UPDATE/DELETE in der App-Logik. Optionale Schema-Constraint via Postgres-Trigger.
- Eval-Context-Leak:
evaluateFlagdarf nie ContextProperties an Client zurückgeben (z.B. email im Reason-Feld) — Sanitization derreason-Felder vor Client-Hydration. - Cache-Poisoning: Cache-Key enthält Hash über Ctx → keine Cross-Tenant-Leaks; Invalidation-Events müssen authentifiziert sein (Pub/Sub-Channel ist internal-only).
Subagent Recommendations
- Planning:
Plan-Subagent mit dieser Detail-MD als Input für Implementation-Sequenz + Test-Pyramide. - Research:
Explore-Subagent: "Analysiere existierendepackages/feature-flags/und alle Caller in apps/web — welche Stellen rufenisEnabled? Welche brauchen Variant-Support? Welche brauchen Plan-Tier-Check?" - Implementation Step 1-3 (Prisma + Targeting + Evaluate):
general-purpose-Subagent mit Brief: "Implementiere Schema-Erweiterung + Targeting-Engine + evaluateFlag gemäß feature-flags.md Steps 1-3. Test-First." - Implementation Step 4 (Cache):
general-purpose-Subagent: "SharedStore-Cache + Pub/Sub-Invalidation gemäß Step 4. Brauchst Phase-03 SharedStore-API." - Implementation Step 5 (Admin-UI):
general-purpose-Subagent +subframe:design-Skill für Rule-Builder-Visuell. Achtung: React-Router-v7-Route-Types richtig importieren. - Implementation Step 6-7 (Audit + Client):
general-purpose-Subagent. - Tests: separater
general-purpose-Subagent für Test-Suite-Aufbau (TestingLibrary, Vitest, Playwright). - Verification:
gsd-verifiermit Acceptance-Criteria-Checkliste. - Code-Review:
gsd-code-reviewernach Task-Completion.
Staging-Deployment-Steps
- Branch
agent/05-feature-flagspushen → Coolify-Auto-Deploy - Migration auf Staging-DB laufen lassen via
pnpm prisma migrate deploy - SharedStore-Container (Redis) muss vorhanden sein (aus Phase 03)
- Smoke-Test auf Staging:
- Admin-UI öffnen, Test-Flag anlegen mit Percentage-Rule 50%
- In incognito-Session 20 Test-User-Logins durchspielen → ca. 10 sehen das Feature, deterministisch
- Flag-Update auf 100% → Pub/Sub-Invalidation prüfen via Worker-Logs
- Audit-Timeline checken
- Performance-Test: 1000 Eval-Aufrufe/s parallel — Cache-Hit-Rate muss >95% sein, p99 Eval-Latency <5ms
Deviations from Plan
- Visual rule-builder UI deferred to follow-up. v1 ships the JSON-rules editor in the admin route plus runtime validation (the action handler re-evaluates the tree against a probe context before persisting). Tree-render with drag-drop + percentage slider + allowlist autocomplete is a separate task; spec already notes this as a major sub-task.
POST /api/feature-flags/preview-affecteddeferred. Live affected-count belongs with the visual builder — without the builder there is no UI that consumes it.- Engine kill-switch
FEATURE_FLAGS_USE_LEGACYnot wired. The v1FeatureFlagsServicekeeps running side-by-side and is@deprecated, so a regression on v2 falls back to v1 by call-site choice. A binary env-toggle is not needed for the initial rollout. - Existing v1 callers not migrated. workspaceRoles / onboarding-gating /
dashboard-gating / rootData all keep using
FeatureFlagsService— their tests rely on the legacy mock surface. The newevaluateFlagForRequest/isFeatureFlagEnabledbridge is the documented migration target for new call-sites; mechanical migration of the 4 existing sites is a follow-up cleanup.
Progress Log
- 2026-05-17 12:23 —
2071881f— extend PrismaFeatureFlagwith rules / variants / enabledFrom / enabledUntil / parentFlagId and add append-onlyFeatureFlagAudittable; migration20260517100000_05_feature_flags_v2. - 2026-05-17 12:30 —
59faa023— new@toolctrl/feature-flagspackage with the 7 targeting rule types (boolean / allowlist / percentage / plan-tier / role-based / time-based / composite) and sticky SHA1 percentage buckets; 29 unit tests including a 10k-sample distribution test. - 2026-05-17 12:33 —
9aadd0d1—evaluateFlag+getFeatureFlagVariantwith FlagLoader-injection (keeps the package Prisma-free), time-window check, parent-flag dependency resolution with cycle-guard, sticky weighted variant selection; 16 new tests. - 2026-05-17 12:39 —
ead777be—createFlagEvalCacheon top of the two-tier cache (#39); singleton + subscriber wired throughcache-bootstrap.server.ts; pub/sub channelfeature-flags:invalidate. - 2026-05-17 12:43 —
2596df58—FeatureFlagProvider+useFeatureFlag(+useFeatureFlagEnabled/useFeatureFlagVariant) with SSR-hydration via root-loader; server bridgeevaluateFlagForContext/evaluateFlagsForContext/invalidateFlagCache; 4 hook tests viareact-dom/server. - 2026-05-17 12:46 —
ceac15f0— admin route/admin/feature-flags/engine(list + toggle + rule-JSON editor + audit timeline). Hardcoded-strings baseline floor bumped (jsx-text0→2,user-facing-prop-literal15→16) with explicit comment inscripts/verify-hardcoded-strings.mjs. - 2026-05-17 12:50 —
0241fe42— request-bound bridgefeatureFlagsRequest.server(evaluateFlagForRequest/isFeatureFlagEnabled); legacyFeatureFlagsServicemarked@deprecatedwith migration pointer. - 2026-05-17 12:54 —
c26acc3f— CLI subtreetoolctrl-cli feature-flags {list,enable,disable,set-rules}; set-rules validates the rule tree viaevaluateRulebefore persisting. - 2026-05-17 12:55 —
eda5608b—docs/features/feature-flags.mdwith rule-tree schema, percentage-hash explanation, admin walkthrough, SSR-hydration code, CLI usage, follow-ups. - 2026-05-17 12:56 — (this commit) — PROGRESS.md row updated to
in_progress (visual-rule-builder-deferred). Engine, cache, hook, admin-CRUD, CLI, docs all ship and tests green (58 in@toolctrl/feature-flags, 123 in@toolctrl/cli). Visual rule-builder + 4-callsite migration tracked as follow-ups under Deviations.