Feature Flags Subsystem for Page/View Enablement

[maany]

Description

The WebUI currently has a few ad-hoc feature toggles (OIDC, UserPass, X509, Multi-VO) managed through EnvConfigGateway, but these only control authentication methods, not which pages, views, or functional areas are available to users.

There is no mechanism to:

Hide or disable entire pages (e.g., disable the Rule Creation page, or the Subscriptions section)
Conditionally show/hide UI elements within a page (e.g., hide the "Approve Rules" tab)
Enforce these restrictions at the routing level (currently no middleware.ts exists — all route protection is auth-only via NextAuth)
This means every deployment exposes the same set of pages regardless of whether the backing Rucio server supports those features or whether the admin wants them available.

Ideas

A Feature Flags subsystem that gates pages, views, and API routes, ideally resolvable at build time.

Feature Registry: A typed configuration declaring which feature domains are enabled. Each feature maps to one or more pages and one or more API routes:

FEATURE_RULES=true           # /rules, /rule/*, /api/feature/list-rules, /api/feature/get-rule, /api/feature/list-rule-replica-lock-states
FEATURE_RULES_CREATE=true    # /rule/create, /api/feature/create-rule
FEATURE_RULES_APPROVE=true   # /rules/approve, /api/feature/list-rules-pending-approval, /api/feature/update-rule (approve action)
FEATURE_SUBSCRIPTIONS=true   # /subscriptions, /subscription/*, /api/feature/list-subscription, /api/feature/get-subscription, /api/feature/list-subscription-rule-states
FEATURE_RSES=true            # /rses, /rse/*, /api/feature/list-rses, /api/feature/list-all-rses, /api/feature/get-rse, /api/feature/get-rse-*
FEATURE_DID_METADATA=true    # /api/feature/get-did-meta, /api/feature/get-did-keyvaluepairs, metadata tab in DID detail view
FEATURE_DID_MUTATE=true      # /api/feature/add-did, /api/feature/attach-dids, /api/feature/set-did-status

2. Build-time resolution — NEXT_PUBLIC_FEATURE_* env vars get inlined by Next.js at build time and tree-shaken from client bundles when disabled. Server-side flags use process.env directly in API routes.

3. API route gating — Each API route handler (e.g., POST /api/feature/create-rule) should check its feature flag early and return 404 (not 403 — disabled features should appear nonexistent, not forbidden) when the feature is off. This could be a shared guard:

// in each route handler, or via a wrapper
if (!featureEnabled('rules.create')) {
  return NextResponse.json({ error: 'Not found' }, { status: 404 });
}

Or a higher-order function wrapping route exports to reduce boilerplate.

4. Route-level enforcement (middleware) — A Next.js middleware.ts that maps page routes to feature flags and redirects/404s for disabled pages. This prevents direct URL navigation to disabled UI.

5. UI-level integration — A component or useFeature('rules.create') hook for conditional rendering. Navigation items in SiteHeader should respect these flags.

Feature to Route Mapping

Feature Key	Pages	API Routes
rules	/rules, /rule/[id]	list-rules, get-rule, list-rule-replica-lock-states
rules.create	/rule/create	create-rule, list-all-rses (when used for rule creation)
rules.approve	/rules/approve	list-rules-pending-approval, update-rule
subscriptions	/subscriptions, /subscription/[account]/*	list-subscription, get-subscription, list-subscription-rule-states
rses	/rses, /rse/[name]/*	list-rses, list-all-rses, get-rse, get-rse-protocols, get-rse-attributes, get-rse-usage
dids.metadata	DID detail metadata tab	get-did-meta, get-did-keyvaluepairs
dids.mutate	DID creation/attach UI	add-did, attach-dids, set-did-status

Potential areas to research

1. Build-time vs. runtime: Build-time is simpler and yields smaller bundles, but requires a rebuild to toggle. Runtime flags (fetched from server config) are more flexible for multi-tenant or containerized deployments. Start with build-time; runtime can layer on later.
2. Shared API routes: Some routes serve multiple features (e.g., list-all-rses is used by both RSE browsing and rule creation). The flag mapping needs to handle OR logic — the route is available if any consuming feature is enabled.
3. Role-based gating: This issue covers deployment-level flags (admin decides what's available). Role-based restrictions (e.g., only admins see "Approve Rules") is a separate concern that layers on top.
4. Existing EnvConfigGateway: The infrastructure for reading env vars and exposing through ports already exists — this extends that pattern.

Checklist of goals to accomplish

• Feature flags declared in environment configuration with env var template updated
• API routes for disabled features return 404
• Pages for disabled features are not reachable via direct URL (middleware redirect or 404)
• Navigation links for disabled features are hidden from SiteHeader
• A component or equivalent for conditional rendering within pages
• A shared API route guard (HOF or utility) to reduce per-route boilerplate
• Build-time resolution preferred where possible
• Existing auth toggles documented alongside new flags (migration optional)

Additional Information

• The Rucio API needs to be changed.