msaas-feature-flags 0.1.0__tar.gz

msaas_feature_flags-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+.next/
+.turbo/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.*
+!.env.example
+!.env.*.example
+!.env.*.template
+.DS_Store
+coverage/
+
+# Runtime artifacts
+logs_llm/
+vectors.db
+vectors.db-shm
+vectors.db-wal

msaas_feature_flags-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: msaas-feature-flags
+Version: 0.1.0
+Summary: Feature flag service with targeting rules, percentage rollout, and caching
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

msaas_feature_flags-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "msaas-feature-flags"
+version = "0.1.0"
+description = "Feature flag service with targeting rules, percentage rollout, and caching"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = [
+    "msaas-api-core",
+    "msaas-errors",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0",
+    "asyncpg>=0.30.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx>=0.27.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/feature_flags"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.uv.sources]
+msaas-api-core = { workspace = true }
+msaas-errors = { workspace = true }

msaas_feature_flags-0.1.0/src/feature_flags/__init__.py

@@ -0,0 +1,40 @@
+"""Willian Flags -- Feature flag service with targeting, rollout, and caching."""
+
+from feature_flags.config import FlagConfig, close_pool, get_pool, init_flags
+from feature_flags.evaluator import clear_cache, evaluate_all, evaluate_flag
+from feature_flags.models import (
+    FeatureFlag,
+    FlagEvaluation,
+    TargetingRule,
+    UserContext,
+)
+from feature_flags.router import FlagRouter
+from feature_flags.store import (
+    create_flag,
+    create_table,
+    delete_flag,
+    get_flag,
+    list_flags,
+    update_flag,
+)
+
+__all__ = [
+    "FlagConfig",
+    "FlagRouter",
+    "FeatureFlag",
+    "FlagEvaluation",
+    "TargetingRule",
+    "UserContext",
+    "clear_cache",
+    "close_pool",
+    "create_flag",
+    "create_table",
+    "delete_flag",
+    "evaluate_all",
+    "evaluate_flag",
+    "get_flag",
+    "get_pool",
+    "init_flags",
+    "list_flags",
+    "update_flag",
+]

msaas_feature_flags-0.1.0/src/feature_flags/config.py

@@ -0,0 +1,46 @@
+"""Feature flag configuration and connection pool management."""
+
+from __future__ import annotations
+
+import asyncpg
+from pydantic import BaseModel, Field
+
+_pool: asyncpg.Pool | None = None
+
+
+class FlagConfig(BaseModel):
+    """Configuration for the feature flag service."""
+
+    database_url: str = Field(
+        description="PostgreSQL connection string (asyncpg format)",
+    )
+    cache_ttl_seconds: int = Field(
+        default=60,
+        description="In-memory cache TTL in seconds",
+    )
+    default_enabled: bool = Field(
+        default=False,
+        description="Default flag state when a flag key is not found",
+    )
+
+
+async def init_flags(config: FlagConfig) -> asyncpg.Pool:
+    """Create and store the asyncpg connection pool."""
+    global _pool
+    _pool = await asyncpg.create_pool(config.database_url, min_size=2, max_size=10)
+    return _pool
+
+
+def get_pool() -> asyncpg.Pool:
+    """Return the current pool. Raises if init_flags() was not called."""
+    if _pool is None:
+        raise RuntimeError("Feature flags not initialized. Call init_flags() first.")
+    return _pool
+
+
+async def close_pool() -> None:
+    """Gracefully close the connection pool."""
+    global _pool
+    if _pool is not None:
+        await _pool.close()
+        _pool = None

msaas_feature_flags-0.1.0/src/feature_flags/evaluator.py

@@ -0,0 +1,148 @@
+"""Flag evaluation engine with targeting rules, percentage rollout, and caching."""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from typing import Any
+
+from feature_flags.config import FlagConfig
+from feature_flags.models import (
+    FeatureFlag,
+    FlagEvaluation,
+    Operator,
+    TargetingRule,
+    UserContext,
+)
+from feature_flags.store import get_flag, list_flags
+
+# ---------------------------------------------------------------------------
+# In-memory cache
+# ---------------------------------------------------------------------------
+
+_cache: dict[str, tuple[FeatureFlag, float]] = {}
+_config: FlagConfig | None = None
+
+
+def configure_evaluator(config: FlagConfig) -> None:
+    """Set the evaluator config (TTL, defaults). Called during app startup."""
+    global _config
+    _config = config
+
+
+def clear_cache() -> None:
+    """Flush all cached flag entries."""
+    _cache.clear()
+
+
+def _get_ttl() -> int:
+    return _config.cache_ttl_seconds if _config else 60
+
+
+def _default_enabled() -> bool:
+    return _config.default_enabled if _config else False
+
+
+def _cache_get(key: str) -> FeatureFlag | None:
+    entry = _cache.get(key)
+    if entry is None:
+        return None
+    flag, ts = entry
+    if time.monotonic() - ts > _get_ttl():
+        del _cache[key]
+        return None
+    return flag
+
+
+def _cache_set(key: str, flag: FeatureFlag) -> None:
+    _cache[key] = (flag, time.monotonic())
+
+
+# ---------------------------------------------------------------------------
+# Deterministic hash for percentage rollout
+# ---------------------------------------------------------------------------
+
+
+def _rollout_hash(user_id: str, flag_key: str) -> int:
+    """Return a deterministic 0-99 bucket from user_id + flag_key."""
+    digest = hashlib.md5(f"{user_id}:{flag_key}".encode(), usedforsecurity=False).digest()
+    return int.from_bytes(digest[:4], "little") % 100
+
+
+# ---------------------------------------------------------------------------
+# Targeting rule matching
+# ---------------------------------------------------------------------------
+
+
+def _match_rule(rule: TargetingRule, user_ctx: UserContext) -> bool:
+    """Evaluate a single targeting rule against a user context."""
+    attr_value = user_ctx.attributes.get(rule.attribute)
+    return _compare(attr_value, rule.operator, rule.value)
+
+
+def _compare(attr_value: Any, op: Operator, rule_value: Any) -> bool:
+    if attr_value is None:
+        return False
+    if op == Operator.eq:
+        return attr_value == rule_value
+    if op == Operator.neq:
+        return attr_value != rule_value
+    if op == Operator.in_:
+        return attr_value in rule_value if isinstance(rule_value, list) else False
+    if op == Operator.not_in:
+        return attr_value not in rule_value if isinstance(rule_value, list) else True
+    if op == Operator.gte:
+        return attr_value >= rule_value
+    if op == Operator.lte:
+        return attr_value <= rule_value
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+async def evaluate_flag(key: str, user_context: UserContext) -> FlagEvaluation:
+    """Evaluate a single feature flag for the given user context.
+
+    Resolution order:
+    1. Flag not found -> default_enabled
+    2. Flag disabled -> disabled
+    3. Targeting rules (all must match if present)
+    4. Percentage rollout
+    """
+    flag = _cache_get(key)
+    if flag is None:
+        flag = await get_flag(key)
+        if flag is None:
+            return FlagEvaluation(flag_key=key, enabled=_default_enabled(), reason="flag_not_found")
+        _cache_set(key, flag)
+
+    if not flag.enabled:
+        return FlagEvaluation(flag_key=key, enabled=False, reason="flag_disabled")
+
+    # Targeting rules: ALL must match (AND logic)
+    if flag.targeting_rules:
+        all_match = all(_match_rule(r, user_context) for r in flag.targeting_rules)
+        if not all_match:
+            return FlagEvaluation(flag_key=key, enabled=False, reason="targeting_rule_mismatch")
+
+    # Percentage rollout
+    if flag.rollout_percentage < 100:
+        bucket = _rollout_hash(user_context.user_id, key)
+        if bucket >= flag.rollout_percentage:
+            return FlagEvaluation(flag_key=key, enabled=False, reason="rollout_excluded")
+
+    return FlagEvaluation(flag_key=key, enabled=True, reason="enabled")
+
+
+async def evaluate_all(user_context: UserContext) -> list[FlagEvaluation]:
+    """Evaluate every flag in the store for the given user context."""
+    flags = await list_flags()
+    results: list[FlagEvaluation] = []
+    for flag in flags:
+        _cache_set(flag.key, flag)
+        result = await evaluate_flag(flag.key, user_context)
+        results.append(result)
+    return results

msaas_feature_flags-0.1.0/src/feature_flags/models.py

@@ -0,0 +1,79 @@
+"""Pydantic models for feature flags, targeting, and evaluation."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class Operator(StrEnum):
+    """Supported targeting rule operators."""
+
+    eq = "eq"
+    neq = "neq"
+    in_ = "in"
+    not_in = "not_in"
+    gte = "gte"
+    lte = "lte"
+
+
+class TargetingRule(BaseModel):
+    """A single targeting rule matched against user attributes."""
+
+    attribute: str = Field(description="User attribute to evaluate (e.g. 'plan', 'country')")
+    operator: Operator = Field(description="Comparison operator")
+    value: Any = Field(description="Value to compare against")
+
+
+class FeatureFlag(BaseModel):
+    """Full representation of a feature flag."""
+
+    id: UUID
+    key: str = Field(description="Unique flag identifier (e.g. 'dark-mode')")
+    name: str = Field(description="Human-readable name")
+    description: str = Field(default="")
+    enabled: bool = Field(default=False)
+    rollout_percentage: int = Field(default=100, ge=0, le=100)
+    targeting_rules: list[TargetingRule] = Field(default_factory=list)
+    created_at: datetime
+    updated_at: datetime
+
+
+class CreateFlagInput(BaseModel):
+    """Input for creating a new feature flag."""
+
+    key: str
+    name: str
+    description: str = ""
+    enabled: bool = False
+    rollout_percentage: int = Field(default=100, ge=0, le=100)
+    targeting_rules: list[TargetingRule] = Field(default_factory=list)
+
+
+class UpdateFlagInput(BaseModel):
+    """Partial update for a feature flag. Only provided fields are updated."""
+
+    name: str | None = None
+    description: str | None = None
+    enabled: bool | None = None
+    rollout_percentage: int | None = Field(default=None, ge=0, le=100)
+    targeting_rules: list[TargetingRule] | None = None
+
+
+class UserContext(BaseModel):
+    """Context about the current user, used for flag targeting and rollout."""
+
+    user_id: str
+    attributes: dict[str, Any] = Field(default_factory=dict)
+
+
+class FlagEvaluation(BaseModel):
+    """Result of evaluating a single flag for a user."""
+
+    flag_key: str
+    enabled: bool
+    reason: str

msaas_feature_flags-0.1.0/src/feature_flags/router.py

@@ -0,0 +1,82 @@
+"""FastAPI router factory for feature flag CRUD and evaluation endpoints."""
+
+from __future__ import annotations
+
+from errors import (
+    ConflictError,
+    NotFoundError,
+)
+from fastapi import APIRouter
+
+from feature_flags.evaluator import evaluate_all, evaluate_flag
+from feature_flags.models import (
+    CreateFlagInput,
+    FeatureFlag,
+    FlagEvaluation,
+    UpdateFlagInput,
+    UserContext,
+)
+from feature_flags.store import (
+    create_flag,
+    delete_flag,
+    get_flag,
+    list_flags,
+    update_flag,
+)
+
+
+def FlagRouter(*, prefix: str = "/flags", tags: list[str] | None = None) -> APIRouter:
+    """Create a FastAPI router with feature flag CRUD and evaluation endpoints.
+
+    Usage:
+        app.include_router(FlagRouter())
+    """
+    router = APIRouter(prefix=prefix, tags=tags or ["feature-flags"])
+
+    @router.get("", response_model=list[FeatureFlag])
+    async def handle_list_flags() -> list[FeatureFlag]:
+        """List all feature flags."""
+        return await list_flags()
+
+    @router.post("", response_model=FeatureFlag, status_code=201)
+    async def handle_create_flag(body: CreateFlagInput) -> FeatureFlag:
+        """Create a new feature flag."""
+        existing = await get_flag(body.key)
+        if existing:
+            raise ConflictError(f"Flag '{body.key}' already exists")
+        return await create_flag(body)
+
+    @router.get("/{key}", response_model=FeatureFlag)
+    async def handle_get_flag(key: str) -> FeatureFlag:
+        """Get a single feature flag by key."""
+        flag = await get_flag(key)
+        if not flag:
+            raise NotFoundError(f"Flag '{key}' not found")
+        return flag
+
+    @router.patch("/{key}", response_model=FeatureFlag)
+    async def handle_update_flag(key: str, body: UpdateFlagInput) -> FeatureFlag:
+        """Partially update a feature flag."""
+        flag = await update_flag(key, body)
+        if not flag:
+            raise NotFoundError(f"Flag '{key}' not found")
+        return flag
+
+    @router.delete("/{key}", status_code=204)
+    async def handle_delete_flag(key: str) -> None:
+        """Delete a feature flag."""
+        deleted = await delete_flag(key)
+        if not deleted:
+            raise NotFoundError(f"Flag '{key}' not found")
+
+    @router.post("/evaluate", response_model=list[FlagEvaluation])
+    async def handle_evaluate(body: UserContext) -> list[FlagEvaluation]:
+        """Evaluate all flags for a given user context."""
+        return await evaluate_all(body)
+
+    @router.post("/evaluate/{key}", response_model=FlagEvaluation)
+    async def handle_evaluate_single(key: str, body: UserContext) -> FlagEvaluation:
+        """Evaluate a single flag for a given user context."""
+        return await evaluate_flag(key, body)
+
+    return router

msaas_feature_flags-0.1.0/src/feature_flags/store.py

@@ -0,0 +1,129 @@
+"""asyncpg-backed CRUD operations for feature flags."""
+
+from __future__ import annotations
+
+import json
+
+import asyncpg
+
+from feature_flags.config import get_pool
+from feature_flags.models import (
+    CreateFlagInput,
+    FeatureFlag,
+    TargetingRule,
+    UpdateFlagInput,
+)
+
+CREATE_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS feature_flags (
+    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    key           TEXT UNIQUE NOT NULL,
+    name          TEXT NOT NULL,
+    description   TEXT NOT NULL DEFAULT '',
+    enabled       BOOLEAN NOT NULL DEFAULT FALSE,
+    rollout_percentage INTEGER NOT NULL DEFAULT 100
+        CHECK (rollout_percentage >= 0 AND rollout_percentage <= 100),
+    targeting_rules JSONB NOT NULL DEFAULT '[]'::jsonb,
+    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_feature_flags_key ON feature_flags (key);
+"""
+
+
+async def create_table(pool: asyncpg.Pool | None = None) -> None:
+    """Create the feature_flags table if it does not exist."""
+    conn_pool = pool or get_pool()
+    await conn_pool.execute(CREATE_TABLE_SQL)
+
+
+def _row_to_flag(row: asyncpg.Record) -> FeatureFlag:
+    """Convert a database row to a FeatureFlag model."""
+    rules_raw = row["targeting_rules"]
+    if isinstance(rules_raw, str):
+        rules_raw = json.loads(rules_raw)
+    rules = [TargetingRule(**r) for r in rules_raw]
+    return FeatureFlag(
+        id=row["id"],
+        key=row["key"],
+        name=row["name"],
+        description=row["description"],
+        enabled=row["enabled"],
+        rollout_percentage=row["rollout_percentage"],
+        targeting_rules=rules,
+        created_at=row["created_at"],
+        updated_at=row["updated_at"],
+    )
+
+
+async def create_flag(data: CreateFlagInput, pool: asyncpg.Pool | None = None) -> FeatureFlag:
+    """Insert a new feature flag and return it."""
+    conn_pool = pool or get_pool()
+    rules_json = json.dumps([r.model_dump(mode="json") for r in data.targeting_rules])
+    row = await conn_pool.fetchrow(
+        """
+        INSERT INTO feature_flags (key, name, description, enabled, rollout_percentage, targeting_rules)
+        VALUES ($1, $2, $3, $4, $5, $6::jsonb)
+        RETURNING *
+        """,
+        data.key,
+        data.name,
+        data.description,
+        data.enabled,
+        data.rollout_percentage,
+        rules_json,
+    )
+    return _row_to_flag(row)
+
+
+async def get_flag(key: str, pool: asyncpg.Pool | None = None) -> FeatureFlag | None:
+    """Fetch a single flag by its key. Returns None if not found."""
+    conn_pool = pool or get_pool()
+    row = await conn_pool.fetchrow("SELECT * FROM feature_flags WHERE key = $1", key)
+    return _row_to_flag(row) if row else None
+
+
+async def list_flags(pool: asyncpg.Pool | None = None) -> list[FeatureFlag]:
+    """Fetch all feature flags ordered by creation date."""
+    conn_pool = pool or get_pool()
+    rows = await conn_pool.fetch("SELECT * FROM feature_flags ORDER BY created_at")
+    return [_row_to_flag(r) for r in rows]
+
+
+async def update_flag(
+    key: str, data: UpdateFlagInput, pool: asyncpg.Pool | None = None
+) -> FeatureFlag | None:
+    """Partially update a flag. Only non-None fields are updated."""
+    conn_pool = pool or get_pool()
+    sets: list[str] = []
+    values: list[object] = []
+    idx = 1
+
+    for field_name in ("name", "description", "enabled", "rollout_percentage"):
+        val = getattr(data, field_name)
+        if val is not None:
+            sets.append(f"{field_name} = ${idx}")
+            values.append(val)
+            idx += 1
+
+    if data.targeting_rules is not None:
+        sets.append(f"targeting_rules = ${idx}::jsonb")
+        values.append(json.dumps([r.model_dump(mode="json") for r in data.targeting_rules]))
+        idx += 1
+
+    if not sets:
+        return await get_flag(key, conn_pool)
+
+    sets.append("updated_at = now()")
+    values.append(key)
+
+    query = f"UPDATE feature_flags SET {', '.join(sets)} WHERE key = ${idx} RETURNING *"
+    row = await conn_pool.fetchrow(query, *values)
+    return _row_to_flag(row) if row else None
+
+
+async def delete_flag(key: str, pool: asyncpg.Pool | None = None) -> bool:
+    """Delete a flag by key. Returns True if a row was deleted."""
+    conn_pool = pool or get_pool()
+    result = await conn_pool.execute("DELETE FROM feature_flags WHERE key = $1", key)
+    return result == "DELETE 1"