simple-module-feature-flags 0.0.1__py3-none-any.whl

feature_flags/__init__.py

@@ -0,0 +1 @@
+"""FeatureFlags module."""

feature_flags/constants.py

@@ -0,0 +1,31 @@
+"""Stable identifiers for the feature_flags module."""
+
+PERM_FEATURE_FLAGS_VIEW = "feature_flags.view"
+PERM_FEATURE_FLAGS_MANAGE = "feature_flags.manage"
+
+# Prefix is load-bearing on SQLite, which has no per-module schemas.
+TABLE_OVERRIDE = "feature_flags_override"
+UQ_OVERRIDE_SCOPE_NAME = "uq_feature_flags_override_scope_scope_id_name"
+
+SCOPE_SYSTEM = "system"
+SCOPE_TENANT = "tenant"
+ALL_SCOPES = (SCOPE_SYSTEM, SCOPE_TENANT)
+# Empty string, not NULL: PG treats NULLs as distinct in unique indexes,
+# which would let two "system" rows for the same flag coexist.
+SYSTEM_SCOPE_ID = ""
+
+SCOPE_MAX_LENGTH = 10
+SCOPE_ID_MAX_LENGTH = 64
+
+LOCALE_NAMESPACE = "feature_flags"
+
+MENU_LABEL = "Feature Flags"
+MENU_URL = "/feature_flags"
+MENU_ICON = "flag"
+MENU_ORDER = 45
+
+PAGE_BROWSE = "FeatureFlags/Browse"
+
+API_PREFIX = "/api/feature_flags"
+VIEW_PREFIX = "/feature_flags"
+QP_TENANT_ID = "tenant_id"

feature_flags/contracts/__init__.py

@@ -0,0 +1,13 @@
+"""feature_flags contracts — public interface for other modules."""
+
+from feature_flags.contracts.schemas import (
+    FeatureFlagOverrideOut,
+    FeatureFlagView,
+    ToggleRequest,
+)
+
+__all__ = [
+    "FeatureFlagOverrideOut",
+    "FeatureFlagView",
+    "ToggleRequest",
+]

feature_flags/contracts/schemas.py

@@ -0,0 +1,47 @@
+"""SQLModel DTOs for the feature_flags module."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import ConfigDict
+from sqlmodel import Field, SQLModel
+
+
+class FeatureFlagOverrideOut(SQLModel):
+    """Stored override row as returned by the service/API."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    scope: str
+    scope_id: str
+    name: str
+    enabled: bool
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+class FeatureFlagView(SQLModel):
+    """A flag as shown in the admin UI for a given scope.
+
+    ``enabled`` is the value an ``is_enabled(name, tenant_id=...)`` call
+    would return for this scope. ``overridden`` reports whether the row
+    that produced ``enabled`` lives at *this* scope (vs. inherited from
+    system or default). ``system_enabled`` exposes the underlying system
+    value when viewing a tenant scope, so the UI can show "inheriting:
+    on/off" next to the toggle.
+    """
+
+    name: str
+    description: str = ""
+    default_enabled: bool
+    enabled: bool
+    overridden: bool
+    system_enabled: bool | None = None
+
+
+class ToggleRequest(SQLModel):
+    """Body for PUT /api/feature_flags/[tenant/{tenant_id}/]{name} — sets an override."""
+
+    enabled: bool = Field(...)

feature_flags/deps.py

@@ -0,0 +1,27 @@
+"""FastAPI dependencies for the feature_flags module."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+from simple_module_core.feature_flags import FeatureFlagRegistry
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from feature_flags.service import FeatureFlagService
+
+
+async def get_feature_flag_service(
+    db: AsyncSession = Depends(get_db),
+) -> FeatureFlagService:
+    return FeatureFlagService(db)
+
+
+def get_feature_flag_registry(request: Request) -> FeatureFlagRegistry:
+    """Return the process-wide FeatureFlagRegistry owned by the framework."""
+    return request.app.state.sm.feature_flags
+
+
+FeatureFlagServiceDep = Annotated[FeatureFlagService, Depends(get_feature_flag_service)]
+FeatureFlagRegistryDep = Annotated[FeatureFlagRegistry, Depends(get_feature_flag_registry)]

feature_flags/endpoints/api.py

@@ -0,0 +1,136 @@
+"""REST API endpoints for feature_flags management."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException
+from simple_module_core.feature_flags import FeatureFlagRegistry
+from simple_module_hosting.permissions import RequiresPermission
+
+from feature_flags.constants import (
+    PERM_FEATURE_FLAGS_MANAGE,
+    PERM_FEATURE_FLAGS_VIEW,
+    SCOPE_TENANT,
+)
+from feature_flags.contracts.schemas import FeatureFlagView, ToggleRequest
+from feature_flags.deps import FeatureFlagRegistryDep, FeatureFlagServiceDep
+
+router = APIRouter()
+
+
+def _ensure_registered(name: str, registry: FeatureFlagRegistry) -> None:
+    # A typo here would silently persist a dead row that ``list_flags`` filters out.
+    if name not in {f.name for f in registry.all_flags}:
+        raise HTTPException(status_code=404, detail="Feature flag not registered")
+
+
+@router.get(
+    "/",
+    response_model=list[FeatureFlagView],
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_VIEW))],
+)
+async def list_flags(
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> list[FeatureFlagView]:
+    return await service.list_flags(registry)
+
+
+@router.get(
+    "/{name}",
+    response_model=FeatureFlagView,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_VIEW))],
+)
+async def get_flag(
+    name: str,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> FeatureFlagView:
+    view = service.build_view(registry, name)
+    if view is None:
+        raise HTTPException(status_code=404, detail="Feature flag not registered")
+    return view
+
+
+@router.put(
+    "/{name}",
+    response_model=FeatureFlagView,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def set_override(
+    name: str,
+    body: ToggleRequest,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> FeatureFlagView:
+    _ensure_registered(name, registry)
+    await service.set_override(name, body.enabled, registry=registry)
+    view = service.build_view(registry, name)
+    assert view is not None  # _ensure_registered already proved it exists
+    return view
+
+
+@router.delete(
+    "/{name}",
+    status_code=204,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def clear_override(
+    name: str,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> None:
+    cleared = await service.clear_override(name, registry=registry)
+    if not cleared:
+        raise HTTPException(status_code=404, detail="No override set for this flag")
+
+
+@router.get(
+    "/tenant/{tenant_id}",
+    response_model=list[FeatureFlagView],
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_VIEW))],
+)
+async def list_flags_for_tenant(
+    tenant_id: str,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> list[FeatureFlagView]:
+    return await service.list_flags(registry, tenant_id=tenant_id)
+
+
+@router.put(
+    "/tenant/{tenant_id}/{name}",
+    response_model=FeatureFlagView,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def set_tenant_override(
+    tenant_id: str,
+    name: str,
+    body: ToggleRequest,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> FeatureFlagView:
+    _ensure_registered(name, registry)
+    await service.set_override(
+        name, body.enabled, registry=registry, scope=SCOPE_TENANT, scope_id=tenant_id
+    )
+    view = service.build_view(registry, name, tenant_id=tenant_id)
+    assert view is not None  # _ensure_registered already proved it exists
+    return view
+
+
+@router.delete(
+    "/tenant/{tenant_id}/{name}",
+    status_code=204,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def clear_tenant_override(
+    tenant_id: str,
+    name: str,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> None:
+    cleared = await service.clear_override(
+        name, registry=registry, scope=SCOPE_TENANT, scope_id=tenant_id
+    )
+    if not cleared:
+        raise HTTPException(status_code=404, detail="No override set for this flag")

feature_flags/endpoints/views.py

@@ -0,0 +1,98 @@
+"""Inertia view endpoints for feature_flags admin UI.
+
+The browse page renders either system-scope or a tenant-scope view of the
+flags. Tenant scope is selected via a ``tenant_id`` query string. The form
+actions for toggling/clearing accept the same ``tenant_id`` query so the
+frontend doesn't need separate routes per scope.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Request
+from inertia import InertiaResponse
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.permissions import RequiresPermission
+from starlette.responses import RedirectResponse
+
+from feature_flags.constants import (
+    MENU_URL,
+    PAGE_BROWSE,
+    PERM_FEATURE_FLAGS_MANAGE,
+    PERM_FEATURE_FLAGS_VIEW,
+    QP_TENANT_ID,
+    SCOPE_SYSTEM,
+    SCOPE_TENANT,
+    SYSTEM_SCOPE_ID,
+)
+from feature_flags.deps import FeatureFlagRegistryDep, FeatureFlagServiceDep
+
+router = APIRouter()
+
+
+def _redirect_for_tenant(tenant_id: str | None) -> RedirectResponse:
+    target = MENU_URL if not tenant_id else f"{MENU_URL}?{QP_TENANT_ID}={tenant_id}"
+    return RedirectResponse(target, status_code=303)
+
+
+def _scope_args(tenant_id: str | None) -> dict[str, str]:
+    if tenant_id:
+        return {"scope": SCOPE_TENANT, "scope_id": tenant_id}
+    return {"scope": SCOPE_SYSTEM, "scope_id": SYSTEM_SCOPE_ID}
+
+
+@router.get(
+    "/",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_VIEW))],
+)
+async def browse(
+    inertia: InertiaDep,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+    tenant_id: str | None = None,
+) -> InertiaResponse:
+    flags = await service.list_flags(registry, tenant_id=tenant_id)
+    tenants = await service.list_tenants_with_overrides()
+    return await inertia.render(
+        PAGE_BROWSE,
+        {
+            "flags": [f.model_dump(mode="json") for f in flags],
+            "tenant_id": tenant_id,
+            "tenants": tenants,
+        },
+    )
+
+
+@router.post(
+    "/{name}/toggle",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def toggle_action(
+    name: str,
+    request: Request,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+    tenant_id: str | None = None,
+) -> RedirectResponse:
+    if name not in {f.name for f in registry.all_flags}:
+        return _redirect_for_tenant(tenant_id)
+    body = await request.json()
+    enabled = bool(body.get("enabled", False))
+    await service.set_override(name, enabled, registry=registry, **_scope_args(tenant_id))
+    return _redirect_for_tenant(tenant_id)
+
+
+@router.post(
+    "/{name}/clear",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def clear_action(
+    name: str,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+    tenant_id: str | None = None,
+) -> RedirectResponse:
+    await service.clear_override(name, registry=registry, **_scope_args(tenant_id))
+    return _redirect_for_tenant(tenant_id)

feature_flags/locales/en.json

@@ -0,0 +1,40 @@
+{
+  "browse": {
+    "title": "Feature Flags",
+    "description": "Toggle features exposed by installed modules. Overrides persist across restarts.",
+    "empty_title": "No feature flags registered",
+    "empty_description": "Modules declare flags via register_feature_flags(); install one to see it here.",
+    "count_one": "{count} flag",
+    "count_other": "{count} flags",
+    "viewing_system": "Viewing system-level flags. Switch scope to override per tenant.",
+    "viewing_tenant": "Viewing overrides for tenant \"{tenant_id}\". Tenant overrides beat the system value.",
+    "tenant_id_label": "Tenant ID",
+    "tenant_id_placeholder": "e.g. acme",
+    "scope_label": "Scope",
+    "scope_system": "System (all tenants)",
+    "scope_tenant": "Specific tenant",
+    "go": "View",
+    "back_to_system": "Back to system view",
+    "tenants_with_overrides": "Tenants with overrides"
+  },
+  "table": {
+    "name": "Flag",
+    "description": "Description",
+    "default": "Default",
+    "status": "Status",
+    "actions": "Actions",
+    "enabled": "Enabled",
+    "disabled": "Disabled",
+    "overridden": "Override active",
+    "following_default": "Following default",
+    "following_system": "Following system",
+    "system_value": "System: {value}",
+    "clear_override": "Clear override"
+  },
+  "toasts": {
+    "enabled": "\"{name}\" enabled",
+    "disabled": "\"{name}\" disabled",
+    "cleared": "Override cleared for \"{name}\"",
+    "toggle_failed": "Failed to update flag"
+  }
+}

feature_flags/models.py

@@ -0,0 +1,42 @@
+"""SQLModel tables for the feature_flags module.
+
+Stores persisted overrides for flags that modules declare via
+``register_feature_flags``. The definition of a flag (name, description,
+default) lives in code; this table only records admin-applied overrides so
+they survive across app restarts.
+
+A row's ``scope`` selects whether the override applies globally
+(``system``, ``scope_id=""``) or to a single tenant (``tenant``,
+``scope_id=<tenant_id>``). Resolution at runtime: tenant > system > default.
+"""
+
+from __future__ import annotations
+
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin
+from sqlalchemy import UniqueConstraint
+from sqlmodel import Field
+
+from feature_flags.constants import (
+    SCOPE_ID_MAX_LENGTH,
+    SCOPE_MAX_LENGTH,
+    SCOPE_SYSTEM,
+    SYSTEM_SCOPE_ID,
+    TABLE_OVERRIDE,
+    UQ_OVERRIDE_SCOPE_NAME,
+)
+
+Base = create_module_base("feature_flags")
+
+
+class FeatureFlagOverride(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """Persisted override for a single feature flag at a given scope."""
+
+    __tablename__ = TABLE_OVERRIDE
+    __table_args__ = (UniqueConstraint("scope", "scope_id", "name", name=UQ_OVERRIDE_SCOPE_NAME),)
+
+    id: int | None = Field(default=None, primary_key=True)
+    scope: str = Field(default=SCOPE_SYSTEM, max_length=SCOPE_MAX_LENGTH, index=True)
+    scope_id: str = Field(default=SYSTEM_SCOPE_ID, max_length=SCOPE_ID_MAX_LENGTH, index=True)
+    name: str = Field(max_length=200, index=True)
+    enabled: bool = Field(default=False)

feature_flags/module.py

@@ -0,0 +1,74 @@
+"""FeatureFlags module definition."""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+from fastapi import APIRouter, FastAPI
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.permissions import PermissionRegistry
+
+from feature_flags.constants import (
+    LOCALE_NAMESPACE,
+    MENU_ICON,
+    MENU_LABEL,
+    MENU_ORDER,
+    MENU_URL,
+    PERM_FEATURE_FLAGS_MANAGE,
+    PERM_FEATURE_FLAGS_VIEW,
+)
+
+
+class FeatureFlagsModule(ModuleBase):
+    meta = ModuleMeta(
+        name="FeatureFlags",
+        route_prefix="/api/feature_flags",
+        view_prefix="/feature_flags",
+    )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from feature_flags.endpoints.api import router as api
+        from feature_flags.endpoints.views import router as views
+
+        api_router.include_router(api)
+        view_router.include_router(views)
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add(
+            MenuItem(
+                label=MENU_LABEL,
+                url=MENU_URL,
+                icon=MENU_ICON,
+                order=MENU_ORDER,
+                section=MenuSection.SIDEBAR,
+            )
+        )
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(
+            "Feature Flags",
+            [
+                PERM_FEATURE_FLAGS_VIEW,
+                PERM_FEATURE_FLAGS_MANAGE,
+            ],
+        )
+
+    def locale_dirs(self) -> dict[str, Path]:
+        base = Path(str(importlib.resources.files(__package__) / "locales"))
+        return {LOCALE_NAMESPACE: base}
+
+    async def on_startup(self, app: FastAPI) -> None:
+        """Load every persisted override into the in-memory registry.
+
+        Called once, after DB init and before the app starts serving. From
+        here on ``registry.is_enabled`` reflects admin overrides even for
+        requests that don't hit this module's endpoints.
+        """
+        from feature_flags.service import FeatureFlagService
+
+        sm = app.state.sm
+        async with sm.db.session_factory() as session:
+            service = FeatureFlagService(session)
+            await service.hydrate_registry(sm.feature_flags)

feature_flags/pages/Browse.tsx

@@ -0,0 +1,277 @@
+import { router, usePage } from '@inertiajs/react';
+import { keys, useT } from '@simple-module-py/i18n';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Card } from '@simple-module-py/ui/components/ui/card';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyMedia,
+  EmptyTitle,
+} from '@simple-module-py/ui/components/ui/empty';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import { Switch } from '@simple-module-py/ui/components/ui/switch';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@simple-module-py/ui/components/ui/table';
+import { usePermissions } from '@simple-module-py/ui/hooks/use-permissions';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import { Flag, RotateCcw } from 'lucide-react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+
+interface FeatureFlag {
+  name: string;
+  description: string;
+  default_enabled: boolean;
+  enabled: boolean;
+  overridden: boolean;
+  system_enabled: boolean | null;
+}
+
+interface Props {
+  flags: FeatureFlag[];
+  tenant_id: string | null;
+  tenants: string[];
+}
+
+function buildPath(tenantId: string | null) {
+  return tenantId ? `/feature_flags?tenant_id=${encodeURIComponent(tenantId)}` : '/feature_flags';
+}
+
+function actionUrl(name: string, action: 'toggle' | 'clear', tenantId: string | null) {
+  const base = `/feature_flags/${name}/${action}`;
+  return tenantId ? `${base}?tenant_id=${encodeURIComponent(tenantId)}` : base;
+}
+
+function Browse() {
+  const { flags, tenant_id, tenants } = usePage<{ props: Props }>().props as unknown as Props;
+  const { t } = useT();
+  const { can } = usePermissions();
+  const canManage = can('feature_flags.manage');
+  const [tenantInput, setTenantInput] = useState(tenant_id ?? '');
+
+  function handleToggle(flag: FeatureFlag, next: boolean) {
+    router.post(
+      actionUrl(flag.name, 'toggle', tenant_id),
+      { enabled: next },
+      {
+        preserveScroll: true,
+        onSuccess: () =>
+          toast.success(
+            next
+              ? t(keys.feature_flags.toasts.enabled, { name: flag.name })
+              : t(keys.feature_flags.toasts.disabled, { name: flag.name }),
+          ),
+        onError: () => toast.error(t(keys.feature_flags.toasts.toggle_failed)),
+      },
+    );
+  }
+
+  function handleClear(flag: FeatureFlag) {
+    router.post(
+      actionUrl(flag.name, 'clear', tenant_id),
+      {},
+      {
+        preserveScroll: true,
+        onSuccess: () => toast.success(t(keys.feature_flags.toasts.cleared, { name: flag.name })),
+        onError: () => toast.error(t(keys.feature_flags.toasts.toggle_failed)),
+      },
+    );
+  }
+
+  function visitTenant(value: string) {
+    router.visit(buildPath(value.trim() || null));
+  }
+
+  return (
+    <PageShell
+      title={t(keys.feature_flags.browse.title)}
+      description={t(keys.feature_flags.browse.description)}
+    >
+      <Card className="mb-4 p-4">
+        <form
+          className="flex flex-wrap items-end gap-3"
+          onSubmit={(e) => {
+            e.preventDefault();
+            visitTenant(tenantInput);
+          }}
+        >
+          <div className="flex-1 min-w-[200px]">
+            <label className="block text-sm font-medium mb-1" htmlFor="tenant_id">
+              {t(keys.feature_flags.browse.tenant_id_label)}
+            </label>
+            <Input
+              id="tenant_id"
+              value={tenantInput}
+              onChange={(e) => setTenantInput(e.target.value)}
+              placeholder={t(keys.feature_flags.browse.tenant_id_placeholder)}
+            />
+          </div>
+          <Button type="submit" variant="default">
+            {t(keys.feature_flags.browse.go)}
+          </Button>
+          {tenant_id && (
+            <Button type="button" variant="ghost" onClick={() => visitTenant('')}>
+              {t(keys.feature_flags.browse.back_to_system)}
+            </Button>
+          )}
+        </form>
+        {tenants.length > 0 && (
+          <div className="mt-3 flex flex-wrap items-center gap-2 text-sm">
+            <span className="text-muted-foreground">
+              {t(keys.feature_flags.browse.tenants_with_overrides)}:
+            </span>
+            {tenants.map((tid) => (
+              <Button
+                key={tid}
+                type="button"
+                size="sm"
+                variant={tid === tenant_id ? 'default' : 'outline'}
+                onClick={() => visitTenant(tid)}
+              >
+                {tid}
+              </Button>
+            ))}
+          </div>
+        )}
+        <p className="mt-3 text-sm text-muted-foreground">
+          {tenant_id
+            ? t(keys.feature_flags.browse.viewing_tenant, { tenant_id })
+            : t(keys.feature_flags.browse.viewing_system)}
+        </p>
+      </Card>
+
+      <div className="mb-4 flex items-center justify-end">
+        {flags.length > 0 && (
+          <p className="text-sm text-muted-foreground">
+            {t(keys.feature_flags.browse.count, { count: flags.length })}
+          </p>
+        )}
+      </div>
+
+      <Card>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead className="sm:px-6">{t(keys.feature_flags.table.name)}</TableHead>
+              <TableHead className="hidden md:table-cell sm:px-6">
+                {t(keys.feature_flags.table.description)}
+              </TableHead>
+              <TableHead className="hidden sm:table-cell sm:px-6">
+                {t(keys.feature_flags.table.default)}
+              </TableHead>
+              <TableHead className="sm:px-6">{t(keys.feature_flags.table.status)}</TableHead>
+              {canManage && (
+                <TableHead className="text-right sm:px-6">
+                  {t(keys.feature_flags.table.actions)}
+                </TableHead>
+              )}
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {flags.map((flag) => (
+              <TableRow key={flag.name}>
+                <TableCell className="sm:px-6">
+                  <div>
+                    <span className="font-medium font-mono text-sm">{flag.name}</span>
+                    {flag.overridden && (
+                      <span className="ml-2 inline-block">
+                        <Badge variant="secondary">{t(keys.feature_flags.table.overridden)}</Badge>
+                      </span>
+                    )}
+                  </div>
+                </TableCell>
+                <TableCell className="hidden md:table-cell sm:px-6">
+                  <span className="text-muted-foreground text-sm line-clamp-2">
+                    {flag.description || '—'}
+                  </span>
+                </TableCell>
+                <TableCell className="hidden sm:table-cell sm:px-6">
+                  <span className="text-muted-foreground text-sm">
+                    {flag.default_enabled
+                      ? t(keys.feature_flags.table.enabled)
+                      : t(keys.feature_flags.table.disabled)}
+                  </span>
+                </TableCell>
+                <TableCell className="sm:px-6">
+                  <div className="flex items-center gap-3">
+                    <Switch
+                      checked={flag.enabled}
+                      onCheckedChange={(checked) => handleToggle(flag, checked === true)}
+                      disabled={!canManage}
+                      aria-label={flag.name}
+                    />
+                    <div className="flex flex-col">
+                      <span className="text-sm text-muted-foreground">
+                        {flag.enabled
+                          ? t(keys.feature_flags.table.enabled)
+                          : t(keys.feature_flags.table.disabled)}
+                      </span>
+                      {tenant_id && flag.system_enabled !== null && (
+                        <span className="text-xs text-muted-foreground">
+                          {t(keys.feature_flags.table.system_value, {
+                            value: flag.system_enabled
+                              ? t(keys.feature_flags.table.enabled)
+                              : t(keys.feature_flags.table.disabled),
+                          })}
+                        </span>
+                      )}
+                    </div>
+                  </div>
+                </TableCell>
+                {canManage && (
+                  <TableCell className="text-right sm:px-6">
+                    {flag.overridden ? (
+                      <Button
+                        variant="ghost"
+                        size="sm"
+                        onClick={() => handleClear(flag)}
+                        title={t(keys.feature_flags.table.clear_override)}
+                      >
+                        <RotateCcw />
+                        <span className="sr-only">
+                          {t(keys.feature_flags.table.clear_override)}
+                        </span>
+                      </Button>
+                    ) : (
+                      <span className="text-xs text-muted-foreground">
+                        {tenant_id
+                          ? t(keys.feature_flags.table.following_system)
+                          : t(keys.feature_flags.table.following_default)}
+                      </span>
+                    )}
+                  </TableCell>
+                )}
+              </TableRow>
+            ))}
+            {flags.length === 0 && (
+              <TableRow>
+                <TableCell colSpan={5} className="h-40">
+                  <Empty>
+                    <EmptyMedia variant="icon">
+                      <Flag className="size-5 text-primary-300" />
+                    </EmptyMedia>
+                    <EmptyTitle>{t(keys.feature_flags.browse.empty_title)}</EmptyTitle>
+                    <EmptyDescription>
+                      {t(keys.feature_flags.browse.empty_description)}
+                    </EmptyDescription>
+                  </Empty>
+                </TableCell>
+              </TableRow>
+            )}
+          </TableBody>
+        </Table>
+      </Card>
+    </PageShell>
+  );
+}
+
+Browse.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
+export default Browse;

feature_flags/service.py

@@ -0,0 +1,189 @@
+"""FeatureFlagService — manages persisted overrides and syncs them to the registry.
+
+Resolution semantics (tenant > system > default) live in
+``simple_module_core.feature_flags``; this layer only persists overrides and
+mirrors mutations into the registry.
+"""
+
+from __future__ import annotations
+
+from simple_module_core.feature_flags import FeatureFlagDefinition, FeatureFlagRegistry
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from feature_flags.constants import SCOPE_SYSTEM, SCOPE_TENANT, SYSTEM_SCOPE_ID
+from feature_flags.contracts.schemas import FeatureFlagOverrideOut, FeatureFlagView
+from feature_flags.models import FeatureFlagOverride
+
+
+def _registry_tenant_id(scope: str, scope_id: str) -> str | None:
+    """Translate a (scope, scope_id) pair into the registry's tenant_id arg."""
+    return scope_id if scope == SCOPE_TENANT else None
+
+
+def _build_view(
+    flag: FeatureFlagDefinition,
+    *,
+    enabled: bool,
+    overridden: bool,
+    system_enabled: bool | None = None,
+) -> FeatureFlagView:
+    return FeatureFlagView(
+        name=flag.name,
+        description=flag.description,
+        default_enabled=flag.default_enabled,
+        enabled=enabled,
+        overridden=overridden,
+        system_enabled=system_enabled,
+    )
+
+
+class FeatureFlagService:
+    """Read/write persisted overrides and keep the in-memory registry in sync.
+
+    The registry is the source of truth for *which* flags exist and their
+    defaults — those come from module code. This service owns the persisted
+    overrides at both system and tenant scope, mirroring every mutation back
+    into the registry so ``is_enabled`` returns the right value without an
+    extra DB hit per request.
+    """
+
+    def __init__(self, db: AsyncSession) -> None:
+        self.db = db
+
+    async def list_overrides(self) -> list[FeatureFlagOverrideOut]:
+        """Every persisted override across all scopes, ordered for stable display."""
+        result = await self.db.execute(
+            select(FeatureFlagOverride).order_by(
+                FeatureFlagOverride.scope,
+                FeatureFlagOverride.scope_id,
+                FeatureFlagOverride.name,
+            )
+        )
+        return [FeatureFlagOverrideOut.model_validate(row) for row in result.scalars()]
+
+    async def list_tenants_with_overrides(self) -> list[str]:
+        """Distinct tenant_ids that have at least one tenant-scope override."""
+        result = await self.db.execute(
+            select(FeatureFlagOverride.scope_id)
+            .where(FeatureFlagOverride.scope == SCOPE_TENANT)
+            .distinct()
+            .order_by(FeatureFlagOverride.scope_id)
+        )
+        return list(result.scalars())
+
+    async def list_flags(
+        self, registry: FeatureFlagRegistry, tenant_id: str | None = None
+    ) -> list[FeatureFlagView]:
+        """Join registered definitions with persisted overrides for admin display.
+
+        When ``tenant_id`` is None, the view is system-scoped: ``enabled``
+        reflects the system override (or default), and ``overridden`` is
+        true when a system row exists. When ``tenant_id`` is set, the view
+        is for that tenant: ``enabled`` is the resolved value the tenant
+        would see at runtime, ``overridden`` flags whether *this tenant*
+        has its own override, and ``system_enabled`` reports the value that
+        would apply if the tenant override were cleared.
+
+        Reads override state from the in-memory registry (kept in sync by
+        every mutation and rehydrated at startup) rather than re-querying
+        the DB, so admin page loads don't pay an O(rows) scan per request.
+        """
+        views: list[FeatureFlagView] = []
+        for flag in sorted(registry.all_flags, key=lambda f: f.name):
+            system_value = registry.system_override(flag.name)
+            system_enabled = system_value if system_value is not None else flag.default_enabled
+            if tenant_id is None:
+                views.append(
+                    _build_view(flag, enabled=system_enabled, overridden=system_value is not None)
+                )
+                continue
+            tenant_value = registry.tenant_override(flag.name, tenant_id)
+            views.append(
+                _build_view(
+                    flag,
+                    enabled=tenant_value if tenant_value is not None else system_enabled,
+                    overridden=tenant_value is not None,
+                    system_enabled=system_enabled,
+                )
+            )
+        return views
+
+    def build_view(
+        self, registry: FeatureFlagRegistry, name: str, tenant_id: str | None = None
+    ) -> FeatureFlagView | None:
+        """Single-flag variant of ``list_flags`` for write-path responses."""
+        flag = next((f for f in registry.all_flags if f.name == name), None)
+        if flag is None:
+            return None
+        system_value = registry.system_override(name)
+        system_enabled = system_value if system_value is not None else flag.default_enabled
+        if tenant_id is None:
+            return _build_view(flag, enabled=system_enabled, overridden=system_value is not None)
+        tenant_value = registry.tenant_override(name, tenant_id)
+        return _build_view(
+            flag,
+            enabled=tenant_value if tenant_value is not None else system_enabled,
+            overridden=tenant_value is not None,
+            system_enabled=system_enabled,
+        )
+
+    async def _find(self, scope: str, scope_id: str, name: str) -> FeatureFlagOverride | None:
+        result = await self.db.execute(
+            select(FeatureFlagOverride).where(
+                FeatureFlagOverride.scope == scope,
+                FeatureFlagOverride.scope_id == scope_id,
+                FeatureFlagOverride.name == name,
+            )
+        )
+        return result.scalar_one_or_none()
+
+    async def set_override(
+        self,
+        name: str,
+        enabled: bool,
+        registry: FeatureFlagRegistry | None = None,
+        scope: str = SCOPE_SYSTEM,
+        scope_id: str = SYSTEM_SCOPE_ID,
+    ) -> FeatureFlagOverrideOut:
+        """Upsert an override at the given scope and mirror it to the registry."""
+        existing = await self._find(scope, scope_id, name)
+        if existing is None:
+            existing = FeatureFlagOverride(
+                scope=scope, scope_id=scope_id, name=name, enabled=enabled
+            )
+            self.db.add(existing)
+            await self.db.flush()
+        elif existing.enabled != enabled:
+            existing.enabled = enabled
+            await self.db.flush()
+        if registry is not None:
+            registry.set_override(name, enabled, tenant_id=_registry_tenant_id(scope, scope_id))
+        return FeatureFlagOverrideOut.model_validate(existing)
+
+    async def clear_override(
+        self,
+        name: str,
+        registry: FeatureFlagRegistry | None = None,
+        scope: str = SCOPE_SYSTEM,
+        scope_id: str = SYSTEM_SCOPE_ID,
+    ) -> bool:
+        """Delete the override at the given scope and revert the registry layer."""
+        existing = await self._find(scope, scope_id, name)
+        if existing is None:
+            return False
+        await self.db.delete(existing)
+        if registry is not None:
+            registry.clear_override(name, tenant_id=_registry_tenant_id(scope, scope_id))
+        return True
+
+    async def hydrate_registry(self, registry: FeatureFlagRegistry) -> int:
+        """Load every persisted override (system + tenant) into the registry at boot."""
+        overrides = await self.list_overrides()
+        for ovr in overrides:
+            registry.set_override(
+                ovr.name,
+                ovr.enabled,
+                tenant_id=_registry_tenant_id(ovr.scope, ovr.scope_id),
+            )
+        return len(overrides)

simple_module_feature_flags-0.0.1.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: simple_module_feature_flags
+Version: 0.0.1
+Summary: Simple feature-flag module with per-tenant overrides and a consumer API for simple_module
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: feature-flags,multi-tenant,simple-module,toggles
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: simple-module-core==0.0.1
+Requires-Dist: simple-module-db==0.0.1
+Requires-Dist: simple-module-hosting==0.0.1
+Description-Content-Type: text/markdown
+
+# simple_module_feature_flags
+
+Feature flags for [simple_module](https://github.com/antosubash/simple_module_python) apps. Global flags with per-tenant overrides, a tiny consumer API, and no external service to run.
+
+## Install
+
+```bash
+pip install simple_module_feature_flags
+```
+
+## What it provides
+
+- `Flag` and `TenantFlagOverride` SQLModel tables.
+- `is_enabled("flag.name", tenant_id=...)` consumer API.
+- Admin UI at `/feature-flags/admin` — toggle flags, add tenant overrides.
+- Cache layer so checking a flag on every request is cheap.
+
+## Usage
+
+Gate a route:
+
+```python
+from feature_flags import is_enabled   # type: ignore[import-not-found]
+from fastapi import APIRouter, Depends, HTTPException
+
+router = APIRouter()
+
+
+@router.get("/new-feature")
+async def new_feature(tenant_id: int = Depends(current_tenant_id)):
+    if not await is_enabled("orders.new_pricing_engine", tenant_id=tenant_id):
+        raise HTTPException(404)
+    return {"rolled_out": True}
+```
+
+Seed a flag in a migration or admin UI:
+
+```python
+# via migration
+Flag(name="orders.new_pricing_engine", enabled=False)
+```
+
+Tenant override:
+
+```python
+TenantFlagOverride(tenant_id=7, flag_name="orders.new_pricing_engine", enabled=True)
+```
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_feature_flags-0.0.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+feature_flags/__init__.py,sha256=2-MI5-QCdUtM0-c57j8-uCZ_lpFSecfzH84gorSLIqo,27
+feature_flags/constants.py,sha256=eVmFf83nyi1yI3sXXDshkGkIkokPSbXo2eE65HW8rRQ,894
+feature_flags/deps.py,sha256=rCHnBHwTFx_2PxH3bdhYqjlwTvnJegYmANiWkacblLo,887
+feature_flags/models.py,sha256=aA4t8mvJAyFrm16w4sXYZRGH4HeOXchY-EucxS7nakE,1559
+feature_flags/module.py,sha256=vX9pRx1KnVnJeYVi_i2kWavwoXYv2tIxCgaelxNPp2w,2350
+feature_flags/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+feature_flags/service.py,sha256=BJsoId79_RnRr7LSc1k5Ms6bQXT7XH5nGW_DPSVynsE,7837
+feature_flags/contracts/__init__.py,sha256=JkGBkOohqMEjeGdkN8ZZ_uzQ1qqOjyJFB9KL-Ukzz-c,276
+feature_flags/contracts/schemas.py,sha256=fia1IW0IkI2yP48Yp9uMoDXnSriUGneYuVey_pcPgQ0,1297
+feature_flags/endpoints/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+feature_flags/endpoints/api.py,sha256=lE0kG3UnQ7KvvTGZpK4LT4_9py1nWdUdxRIUUvzDAfU,4179
+feature_flags/endpoints/views.py,sha256=sqdgd_OPYiGKdkI0e7SzwMw5tvQ5K-mWFo7OrMLwX_g,3065
+feature_flags/locales/en.json,sha256=BKoMFbnHEH3Q0Y0t5kHOaXl6SoXvOiQpBUAexb8Qyhg,1487
+feature_flags/pages/Browse.tsx,sha256=MPBePp2vl7t9ODU4GAuOojEbbBEdl8WEKZhb7ukqOZo,10346
+simple_module_feature_flags-0.0.1.dist-info/METADATA,sha256=a3PWObqIC6xIEigCrX6EzA9UzxdKagI82PmiG3eFni0,2720
+simple_module_feature_flags-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+simple_module_feature_flags-0.0.1.dist-info/entry_points.txt,sha256=-_bxddecOgjR9-dLOTGYrXwM-KKj2Bg82w36O6uQ9jg,72
+simple_module_feature_flags-0.0.1.dist-info/licenses/LICENSE,sha256=Yn66lhLklsF5p7pa85_ksQrJ79Q-FgOaUAHevLBjer4,1068
+simple_module_feature_flags-0.0.1.dist-info/RECORD,,

simple_module_feature_flags-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

simple_module_feature_flags-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[simple_module]
+feature_flags = feature_flags.module:FeatureFlagsModule

simple_module_feature_flags-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anto Subash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.