Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/05-business-features/feature-flags.md
T

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 — nur isEnabled(name, tenantId)
  • apps/web/app/utils/services/featureFlags.ts — Hardcoded-Mapping aus DB-Row → boolean
  • prisma/schema.prisma — FeatureFlag-Model nur mit name, 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 Tenant
  • 05-business-features/ai-cost-phase-3.md (#56) — Overage-Aktivierung pro Tenant
  • 05-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-Gating
  • 07-chatbot/chatbot-mvp.md (#67) — Chatbot-Rollout per Flag pro Tenant
  • 08-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:

  1. Storage-Layer — Prisma-Models FeatureFlag + FeatureFlagAudit (Schema-Erweiterung).
  2. Evaluation-Layer — evaluateFlag(name, ctx) / getFeatureFlagVariant(name, ctx) in packages/feature-flags/.
  3. Cache-Layer — (flagName, contextHash) → result für 60s, Invalidation per Pub/Sub-Channel feature-flags:invalidate.
  4. Admin-UI — visueller Rule-Builder, Variant-Editor, Live-Affected-Count.
  5. 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

  1. Prisma-Schema-Erweiterung — FeatureFlag-Model um rules Json, variants Json[], enabledFrom DateTime?, enabledUntil DateTime?, parentFlagId String? erweitern + neues Model FeatureFlagAudit { 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
  2. 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
  3. evaluateFlag + getFeatureFlagVariant Public-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
  4. Eval-Cache via SharedStore + Pub/Sub-Invalidation — Cache-Key: ff:{flagName}:{hash(ctx)} mit 60s-TTL. Beim Flag-Update Pub/Sub-Event feature-flags:invalidate mit { 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
  5. 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-Call POST /api/feature-flags/preview-affected der 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
  6. Audit-Trail — jede Mutation (Create/Update/Delete) schreibt FeatureFlagAudit-Row mit actorUserId, 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
  7. Client-SDK + SSR-Hook — useFeatureFlag(name): { enabled, variant }. In root.tsx-Loader werden alle vom Route-Tree benötigten Flags vorab evaluiert und über Context an Client gehydrated. Pattern: loader ruft evaluateFlags(['flag-a', 'flag-b'], ctx) → liefert Map → in LoaderData → Provider im Component-Tree → useFeatureFlag liest 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
  8. Doku — docs/features/feature-flags.md mit Targeting-Patterns (Gradual-Rollout, Allowlist-Beta, Killswitch, A/B-Test, Plan-Gating), Code-Beispielen für evaluateFlag und useFeatureFlag, Admin-UI-Walkthrough, Cache-Verhalten-Erklärung, Audit-Trail-Lesehinweis.
    • Files: docs/features/feature-flags.md
    • Commit: 05/feature-flags: docs

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-Auswahl
    • cache.test.ts — TTL-Verhalten, Pub/Sub-Invalidation-Listener löscht keys
    • useFeatureFlag.test.tsx — React-Testing-Library: Provider + Hook + SSR-Hydration-Szenario
  • Integration-Tests:
    • End-to-End: Flag in DB anlegen → evaluateFlag in 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
  • 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
  • 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 unter apps/web/tests/e2e/feature-flags.spec.ts

NICHT als completed markieren bevor alle Tests grün sind.

Acceptance Criteria

  • Prisma-Schema-Migration applied; FeatureFlag + FeatureFlagAudit mit allen neuen Feldern live
  • packages/feature-flags/ exportiert evaluateFlag, 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 useFeatureFlag mit SSR-Hydration verfügbar
  • Dependency-Hierarchie funktioniert (Parent disabled → Child immer false)
  • docs/features/feature-flags.md mit allen Patterns + Code-Beispielen
  • pnpm lint, pnpm typecheck, pnpm test grü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-Function isEnabled(name, ctx) = evaluateFlag(name, ctx).enabled für Backward-Compat.
  • Feature-Flag-Killswitch: Meta-Flag feature-flags-engine-v2 selbst — wenn false, fallback auf alte boolean-only-Logik via Env-Toggle FEATURE_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: evaluateFlag darf nie ContextProperties an Client zurückgeben (z.B. email im Reason-Feld) — Sanitization der reason-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 existierende packages/feature-flags/ und alle Caller in apps/web — welche Stellen rufen isEnabled? 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-verifier mit Acceptance-Criteria-Checkliste.
  • Code-Review: gsd-code-reviewer nach Task-Completion.

Staging-Deployment-Steps

  1. Branch agent/05-feature-flags pushen → Coolify-Auto-Deploy
  2. Migration auf Staging-DB laufen lassen via pnpm prisma migrate deploy
  3. SharedStore-Container (Redis) muss vorhanden sein (aus Phase 03)
  4. 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
  5. 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-affected deferred. Live affected-count belongs with the visual builder — without the builder there is no UI that consumes it.
  • Engine kill-switch FEATURE_FLAGS_USE_LEGACY not wired. The v1 FeatureFlagsService keeps 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 new evaluateFlagForRequest / isFeatureFlagEnabled bridge 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 Prisma FeatureFlag with rules / variants / enabledFrom / enabledUntil / parentFlagId and add append-only FeatureFlagAudit table; migration 20260517100000_05_feature_flags_v2.
  • 2026-05-17 12:30 — 59faa023 — new @toolctrl/feature-flags package 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 + getFeatureFlagVariant with 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 — createFlagEvalCache on top of the two-tier cache (#39); singleton + subscriber wired through cache-bootstrap.server.ts; pub/sub channel feature-flags:invalidate.
  • 2026-05-17 12:43 — 2596df58 — FeatureFlagProvider + useFeatureFlag (+ useFeatureFlagEnabled / useFeatureFlagVariant) with SSR-hydration via root-loader; server bridge evaluateFlagForContext / evaluateFlagsForContext / invalidateFlagCache; 4 hook tests via react-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-text 0→2, user-facing-prop-literal 15→16) with explicit comment in scripts/verify-hardcoded-strings.mjs.
  • 2026-05-17 12:50 — 0241fe42 — request-bound bridge featureFlagsRequest.server (evaluateFlagForRequest / isFeatureFlagEnabled); legacy FeatureFlagsService marked @deprecated with migration pointer.
  • 2026-05-17 12:54 — c26acc3f — CLI subtree toolctrl-cli feature-flags {list,enable,disable,set-rules}; set-rules validates the rule tree via evaluateRule before persisting.
  • 2026-05-17 12:55 — eda5608b — docs/features/feature-flags.md with 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.