fast-feature-admin 0.0.1__tar.gz

fast_feature_admin-0.0.1/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: fast-feature-admin
+Version: 0.0.1
+Summary: Admin JSON API and server-rendered web console for fast-feature.
+Author: byunjuneseok
+Author-email: byunjuneseok <byunjuneseok@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: fast-feature-core==0.0.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic>=2.6
+Requires-Dist: jinja2>=3.1
+Requires-Dist: python-multipart>=0.0.9
+Requires-Python: >=3.10

fast_feature_admin-0.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "fast-feature-admin"
+version = "0.0.1"
+description = "Admin JSON API and server-rendered web console for fast-feature."
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "byunjuneseok", email = "byunjuneseok@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fast-feature-core==0.0.1",
+    "fastapi>=0.110",
+    "pydantic>=2.6",
+    "jinja2>=3.1",
+    "python-multipart>=0.0.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "fast_feature.admin"
+
+[tool.uv.sources]
+fast-feature-core = { workspace = true }

fast_feature_admin-0.0.1/src/fast_feature/admin/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .router import AdminRouter
+from .service import ManagementService
+
+__all__ = ["AdminRouter", "ManagementService"]

fast_feature_admin-0.0.1/src/fast_feature/admin/router/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .router import AdminRouter
+
+__all__ = ["AdminRouter"]

fast_feature_admin-0.0.1/src/fast_feature/admin/router/router.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request, Response
+from fastapi.params import Depends
+from fastapi.responses import HTMLResponse, RedirectResponse
+from fastapi.templating import Jinja2Templates
+from pydantic import ValidationError
+from starlette.datastructures import FormData
+
+from fast_feature.core import (
+    FlagAlreadyExistsError,
+    FlagNotFoundError,
+    FlagRepository,
+    InvalidFlagError,
+)
+
+from ..schemas import FlagCreate, FlagToggle, FlagUpdate, FlagView
+from ..service import ManagementService
+
+_TEMPLATES_DIR = Path(__file__).resolve().parents[1] / "templates"
+
+
+class AdminRouter:
+    """Builds a pluggable admin ``APIRouter``: JSON CRUD under ``/api/flags``
+    plus an optional server-rendered console under ``/``.
+
+        app.include_router(AdminRouter.build(repository), prefix="/admin")
+
+    Pass ``dependencies`` (e.g. an auth guard) to protect every route.
+    """
+
+    def __init__(
+        self,
+        repository: FlagRepository,
+        *,
+        dependencies: Sequence[Depends] | None = None,
+        ui: bool = True,
+    ) -> None:
+        self._service = ManagementService(repository)
+        self._router = APIRouter(dependencies=list(dependencies or []))
+        self._templates = Jinja2Templates(directory=str(_TEMPLATES_DIR))
+        self._register_json_routes()
+        if ui:
+            self._register_ui_routes()
+
+    @property
+    def router(self) -> APIRouter:
+        return self._router
+
+    @classmethod
+    def build(
+        cls,
+        repository: FlagRepository,
+        *,
+        dependencies: Sequence[Depends] | None = None,
+        ui: bool = True,
+    ) -> APIRouter:
+        return cls(repository, dependencies=dependencies, ui=ui).router
+
+    # --- JSON API ------------------------------------------------------------
+
+    def _register_json_routes(self) -> None:
+        router = self._router
+        router.add_api_route(
+            "/api/flags", self._list, methods=["GET"], response_model=list[FlagView]
+        )
+        router.add_api_route(
+            "/api/flags", self._create, methods=["POST"], response_model=FlagView, status_code=201
+        )
+        router.add_api_route(
+            "/api/flags/{key}", self._get, methods=["GET"], response_model=FlagView
+        )
+        router.add_api_route(
+            "/api/flags/{key}", self._update, methods=["PUT"], response_model=FlagView
+        )
+        router.add_api_route(
+            "/api/flags/{key}", self._toggle, methods=["PATCH"], response_model=FlagView
+        )
+        router.add_api_route("/api/flags/{key}", self._delete, methods=["DELETE"], status_code=204)
+
+    async def _list(self) -> list[FlagView]:
+        return [FlagView.from_flag(flag) for flag in await self._service.list_flags()]
+
+    async def _create(self, body: FlagCreate) -> FlagView:
+        try:
+            flag = body.to_flag()
+        except InvalidFlagError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+        try:
+            created = await self._service.create_flag(flag)
+        except FlagAlreadyExistsError as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        return FlagView.from_flag(created)
+
+    async def _get(self, key: str) -> FlagView:
+        flag = await self._service.get_flag(key)
+        if flag is None:
+            raise HTTPException(status_code=404, detail=f"Flag {key!r} was not found")
+        return FlagView.from_flag(flag)
+
+    async def _update(self, key: str, body: FlagUpdate) -> FlagView:
+        try:
+            flag = body.to_flag(key)
+        except InvalidFlagError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+        try:
+            updated = await self._service.update_flag(flag)
+        except FlagNotFoundError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        return FlagView.from_flag(updated)
+
+    async def _toggle(self, key: str, body: FlagToggle) -> FlagView:
+        try:
+            flag = await self._service.toggle(key, enabled=body.enabled)
+        except FlagNotFoundError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        return FlagView.from_flag(flag)
+
+    async def _delete(self, key: str) -> Response:
+        try:
+            await self._service.delete_flag(key)
+        except FlagNotFoundError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        return Response(status_code=204)
+
+    # --- web console ---------------------------------------------------------
+
+    def _register_ui_routes(self) -> None:
+        router = self._router
+        router.add_api_route(
+            "/", self._ui_list, methods=["GET"], response_class=HTMLResponse, name="admin:list"
+        )
+        router.add_api_route(
+            "/new", self._ui_new, methods=["GET"], response_class=HTMLResponse, name="admin:new"
+        )
+        router.add_api_route("/new", self._ui_create, methods=["POST"], name="admin:create")
+        router.add_api_route(
+            "/{key}/edit",
+            self._ui_edit,
+            methods=["GET"],
+            response_class=HTMLResponse,
+            name="admin:edit",
+        )
+        router.add_api_route("/{key}/edit", self._ui_update, methods=["POST"], name="admin:update")
+        router.add_api_route(
+            "/{key}/toggle", self._ui_toggle, methods=["POST"], name="admin:toggle"
+        )
+        router.add_api_route(
+            "/{key}/delete", self._ui_delete, methods=["POST"], name="admin:delete"
+        )
+
+    async def _ui_list(self, request: Request) -> Response:
+        flags = await self._service.list_flags()
+        return self._templates.TemplateResponse(request, "list.html", {"flags": flags})
+
+    async def _ui_new(self, request: Request) -> Response:
+        return self._render_form(request, flag=None, error=None)
+
+    async def _ui_create(self, request: Request) -> Response:
+        form = await request.form()
+        try:
+            flag = FlagCreate(**self._parse_form(form, with_key=True)).to_flag()
+            await self._service.create_flag(flag)
+        except (InvalidFlagError, FlagAlreadyExistsError, ValidationError, ValueError) as exc:
+            return self._render_form(request, flag=None, error=str(exc), status_code=400)
+        return RedirectResponse(str(request.url_for("admin:list")), status_code=303)
+
+    async def _ui_edit(self, request: Request, key: str) -> Response:
+        flag = await self._service.get_flag(key)
+        if flag is None:
+            raise HTTPException(status_code=404, detail=f"Flag {key!r} was not found")
+        return self._render_form(request, flag=flag, error=None)
+
+    async def _ui_update(self, request: Request, key: str) -> Response:
+        form = await request.form()
+        try:
+            flag = FlagUpdate(**self._parse_form(form, with_key=False)).to_flag(key)
+            await self._service.update_flag(flag)
+        except (InvalidFlagError, FlagNotFoundError, ValidationError, ValueError) as exc:
+            existing = await self._service.get_flag(key)
+            return self._render_form(request, flag=existing, error=str(exc), status_code=400)
+        return RedirectResponse(str(request.url_for("admin:list")), status_code=303)
+
+    async def _ui_toggle(self, request: Request, key: str) -> Response:
+        form = await request.form()
+        enabled = self._text(form, "enabled").lower() in ("1", "true", "on", "yes")
+        try:
+            await self._service.toggle(key, enabled=enabled)
+        except FlagNotFoundError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        return RedirectResponse(str(request.url_for("admin:list")), status_code=303)
+
+    async def _ui_delete(self, request: Request, key: str) -> Response:
+        try:
+            await self._service.delete_flag(key)
+        except FlagNotFoundError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        return RedirectResponse(str(request.url_for("admin:list")), status_code=303)
+
+    # --- helpers -------------------------------------------------------------
+
+    def _render_form(
+        self, request: Request, *, flag: Any, error: str | None, status_code: int = 200
+    ) -> Response:
+        context = {
+            "flag": flag,
+            "error": error,
+            "variants_json": json.dumps(flag.variants, indent=2) if flag else "",
+            "targeting_json": json.dumps(flag.targeting, indent=2)
+            if flag and flag.targeting
+            else "",
+            "metadata_json": json.dumps(flag.metadata, indent=2) if flag and flag.metadata else "",
+        }
+        return self._templates.TemplateResponse(
+            request, "form.html", context, status_code=status_code
+        )
+
+    @classmethod
+    def _parse_form(cls, form: FormData, *, with_key: bool) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "variants": json.loads(cls._text(form, "variants") or "{}"),
+            "default_variant": cls._text(form, "default_variant").strip(),
+            "state": cls._text(form, "state") or "ENABLED",
+        }
+        if with_key:
+            data["key"] = cls._text(form, "key").strip()
+        targeting = cls._text(form, "targeting").strip()
+        data["targeting"] = json.loads(targeting) if targeting else None
+        metadata = cls._text(form, "metadata").strip()
+        data["metadata"] = json.loads(metadata) if metadata else {}
+        return data
+
+    @staticmethod
+    def _text(form: FormData, name: str) -> str:
+        value = form.get(name)
+        return value if isinstance(value, str) else ""

fast_feature_admin-0.0.1/src/fast_feature/admin/schemas/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from .flag_create import FlagCreate
+from .flag_toggle import FlagToggle
+from .flag_update import FlagUpdate
+from .flag_view import FlagView
+
+__all__ = ["FlagCreate", "FlagUpdate", "FlagToggle", "FlagView"]

fast_feature_admin-0.0.1/src/fast_feature/admin/schemas/flag_create.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from fast_feature.core import Flag, FlagState
+
+
+class FlagCreate(BaseModel):
+    key: str
+    variants: dict[str, Any]
+    default_variant: str
+    state: FlagState = FlagState.ENABLED
+    targeting: dict[str, Any] | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def to_flag(self) -> Flag:
+        return Flag(
+            key=self.key,
+            variants=self.variants,
+            default_variant=self.default_variant,
+            state=self.state,
+            targeting=self.targeting,
+            metadata=self.metadata,
+        )

fast_feature_admin-0.0.1/src/fast_feature/admin/schemas/flag_toggle.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class FlagToggle(BaseModel):
+    enabled: bool

fast_feature_admin-0.0.1/src/fast_feature/admin/schemas/flag_update.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from fast_feature.core import Flag, FlagState
+
+
+class FlagUpdate(BaseModel):
+    variants: dict[str, Any]
+    default_variant: str
+    state: FlagState = FlagState.ENABLED
+    targeting: dict[str, Any] | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def to_flag(self, key: str) -> Flag:
+        return Flag(
+            key=key,
+            variants=self.variants,
+            default_variant=self.default_variant,
+            state=self.state,
+            targeting=self.targeting,
+            metadata=self.metadata,
+        )

fast_feature_admin-0.0.1/src/fast_feature/admin/schemas/flag_view.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel
+
+from fast_feature.core import Flag, FlagState
+
+
+class FlagView(BaseModel):
+    key: str
+    variants: dict[str, Any]
+    default_variant: str
+    state: FlagState
+    targeting: dict[str, Any] | None = None
+    metadata: dict[str, Any] = {}
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    @classmethod
+    def from_flag(cls, flag: Flag) -> FlagView:
+        return cls(
+            key=flag.key,
+            variants=flag.variants,
+            default_variant=flag.default_variant,
+            state=flag.state,
+            targeting=flag.targeting,
+            metadata=flag.metadata,
+            created_at=flag.created_at,
+            updated_at=flag.updated_at,
+        )

fast_feature_admin-0.0.1/src/fast_feature/admin/service/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .management_service import ManagementService
+
+__all__ = ["ManagementService"]

fast_feature_admin-0.0.1/src/fast_feature/admin/service/management_service.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from fast_feature.core import Flag, FlagNotFoundError, FlagRepository, FlagState
+
+
+class ManagementService:
+    """Flag administration use cases on top of a ``FlagRepository``."""
+
+    def __init__(self, repository: FlagRepository) -> None:
+        self._repository = repository
+
+    async def list_flags(self) -> list[Flag]:
+        return await self._repository.list_all()
+
+    async def get_flag(self, key: str) -> Flag | None:
+        return await self._repository.get(key)
+
+    async def create_flag(self, flag: Flag) -> Flag:
+        return await self._repository.create(flag)
+
+    async def update_flag(self, flag: Flag) -> Flag:
+        return await self._repository.update(flag)
+
+    async def delete_flag(self, key: str) -> None:
+        await self._repository.delete(key)
+
+    async def toggle(self, key: str, *, enabled: bool) -> Flag:
+        flag = await self._repository.get(key)
+        if flag is None:
+            raise FlagNotFoundError(key)
+        flag.state = FlagState.ENABLED if enabled else FlagState.DISABLED
+        return await self._repository.update(flag)

fast_feature_admin-0.0.1/src/fast_feature/admin/templates/base.html

@@ -0,0 +1,24 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{% block title %}fast-feature admin{% endblock %}</title>
+    <style>
+      :root { color-scheme: light dark; }
+      body { font-family: system-ui, sans-serif; margin: 2rem auto; max-width: 60rem; padding: 0 1rem; }
+      h1 a { color: inherit; text-decoration: none; }
+      table { width: 100%; border-collapse: collapse; }
+      th, td { text-align: left; padding: 0.5rem; border-bottom: 1px solid #8884; }
+      form.inline { display: inline; }
+      label { display: block; margin: 0.75rem 0; }
+      textarea { width: 100%; min-height: 6rem; font-family: ui-monospace, monospace; }
+      .error { color: #b00020; font-weight: 600; }
+      button, a.button { cursor: pointer; }
+    </style>
+  </head>
+  <body>
+    <header><h1><a href="{{ request.url_for('admin:list') }}">fast-feature</a></h1></header>
+    <main>{% block content %}{% endblock %}</main>
+  </body>
+</html>

fast_feature_admin-0.0.1/src/fast_feature/admin/templates/form.html

@@ -0,0 +1,29 @@
+{% extends "base.html" %}
+{% block content %}
+  <p><a href="{{ request.url_for('admin:list') }}">&larr; Back</a></p>
+  {% if error %}<p class="error">{{ error }}</p>{% endif %}
+  <form method="post"
+        action="{{ request.url_for('admin:create') if flag is none
+                   else request.url_for('admin:update', key=flag.key) }}">
+    {% if flag is none %}
+      <label>Key <input name="key" required /></label>
+    {% else %}
+      <p><strong>Key:</strong> {{ flag.key }}</p>
+    {% endif %}
+    <label>Default variant
+      <input name="default_variant" value="{{ flag.default_variant if flag else '' }}" required />
+    </label>
+    <label>State
+      <select name="state">
+        <option value="ENABLED"
+          {{ 'selected' if not flag or flag.state.value == 'ENABLED' else '' }}>ENABLED</option>
+        <option value="DISABLED"
+          {{ 'selected' if flag and flag.state.value == 'DISABLED' else '' }}>DISABLED</option>
+      </select>
+    </label>
+    <label>Variants (JSON)<textarea name="variants" required>{{ variants_json }}</textarea></label>
+    <label>Targeting (JSON, optional)<textarea name="targeting">{{ targeting_json }}</textarea></label>
+    <label>Metadata (JSON, optional)<textarea name="metadata">{{ metadata_json }}</textarea></label>
+    <button type="submit">Save</button>
+  </form>
+{% endblock %}

fast_feature_admin-0.0.1/src/fast_feature/admin/templates/list.html

@@ -0,0 +1,38 @@
+{% extends "base.html" %}
+{% block content %}
+  <p><a class="button" href="{{ request.url_for('admin:new') }}">New flag</a></p>
+  {% if not flags %}
+    <p>No flags yet.</p>
+  {% else %}
+    <table>
+      <thead>
+        <tr><th>Key</th><th>State</th><th>Default</th><th>Variants</th><th>Actions</th></tr>
+      </thead>
+      <tbody>
+        {% for flag in flags %}
+          <tr>
+            <td>{{ flag.key }}</td>
+            <td>{{ flag.state.value }}</td>
+            <td>{{ flag.default_variant }}</td>
+            <td>{{ flag.variants | length }}</td>
+            <td>
+              <form class="inline" method="post"
+                    action="{{ request.url_for('admin:toggle', key=flag.key) }}">
+                <input type="hidden" name="enabled"
+                       value="{{ 'false' if flag.state.value == 'ENABLED' else 'true' }}" />
+                <button type="submit">
+                  {{ 'Disable' if flag.state.value == 'ENABLED' else 'Enable' }}
+                </button>
+              </form>
+              <a href="{{ request.url_for('admin:edit', key=flag.key) }}">Edit</a>
+              <form class="inline" method="post"
+                    action="{{ request.url_for('admin:delete', key=flag.key) }}">
+                <button type="submit">Delete</button>
+              </form>
+            </td>
+          </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+  {% endif %}
+{% endblock %}