fast-feature-ofrep 0.0.1__tar.gz

fast_feature_ofrep-0.0.1/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: fast-feature-ofrep
+Version: 0.0.1
+Summary: OpenFeature Remote Evaluation Protocol (OFREP) HTTP layer 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: fast-feature-engine==0.0.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic>=2.6
+Requires-Python: >=3.10

fast_feature_ofrep-0.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "fast-feature-ofrep"
+version = "0.0.1"
+description = "OpenFeature Remote Evaluation Protocol (OFREP) HTTP layer 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",
+    "fast-feature-engine==0.0.1",
+    "fastapi>=0.110",
+    "pydantic>=2.6",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "fast_feature.ofrep"
+
+[tool.uv.sources]
+fast-feature-core = { workspace = true }
+fast-feature-engine = { workspace = true }

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .errors import OfrepError
+from .router import OfrepRouter
+from .service import EvaluationService
+
+__all__ = ["OfrepRouter", "EvaluationService", "OfrepError"]

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/errors/__init__.py

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

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/errors/base.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+
+class OfrepError(Exception):
+    """Base class for all OFREP-layer errors.
+
+    Storage or engine failures are translated into this at the service
+    boundary (with chaining) so the HTTP layer never couples to a dependency's
+    concrete exception types.
+    """

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/router/__init__.py

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

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/router/router.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from fastapi import APIRouter, Request, Response
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from fast_feature.core import ErrorCode, FlagRepository
+from fast_feature.engine import TargetingEngine
+
+from ..schemas import (
+    BulkEvaluationRequest,
+    BulkEvaluationSuccess,
+    EvaluationFailure,
+    EvaluationRequest,
+    EvaluationSuccess,
+    FlagNotFound,
+)
+from ..service import EvaluationService
+
+
+class OfrepRouter:
+    """Builds a pluggable ``APIRouter`` exposing the OFREP endpoints.
+
+    Mount it onto any FastAPI app::
+
+        app.include_router(OfrepRouter.build(repository))
+    """
+
+    def __init__(
+        self, repository: FlagRepository, *, engine: TargetingEngine | None = None
+    ) -> None:
+        self._service = EvaluationService(repository, engine=engine)
+        self._router = APIRouter(prefix="/ofrep/v1", tags=["OFREP"])
+        self._register_routes()
+
+    @property
+    def router(self) -> APIRouter:
+        return self._router
+
+    @classmethod
+    def build(
+        cls, repository: FlagRepository, *, engine: TargetingEngine | None = None
+    ) -> APIRouter:
+        return cls(repository, engine=engine).router
+
+    def _register_routes(self) -> None:
+        self._router.add_api_route("/evaluate/flags/{key}", self._evaluate_flag, methods=["POST"])
+        self._router.add_api_route("/evaluate/flags", self._evaluate_all, methods=["POST"])
+
+    async def _evaluate_flag(self, key: str, request: EvaluationRequest) -> Response:
+        outcome = await self._service.evaluate(key, request.context)
+        if outcome.error_code is ErrorCode.FLAG_NOT_FOUND:
+            return self._json(404, FlagNotFound.from_outcome(outcome))
+        if outcome.is_error:
+            return self._json(400, EvaluationFailure.from_outcome(outcome))
+        return self._json(200, EvaluationSuccess.from_outcome(outcome))
+
+    async def _evaluate_all(
+        self, request: BulkEvaluationRequest, http_request: Request
+    ) -> Response:
+        outcomes = await self._service.evaluate_all(request.context)
+        payload = BulkEvaluationSuccess.from_outcomes(outcomes).model_dump(
+            by_alias=True, exclude_none=True
+        )
+        etag = self._etag(payload)
+        if http_request.headers.get("if-none-match") == etag:
+            return Response(status_code=304, headers={"ETag": etag})
+        return JSONResponse(status_code=200, content=payload, headers={"ETag": etag})
+
+    @staticmethod
+    def _json(status_code: int, model: BaseModel) -> JSONResponse:
+        return JSONResponse(
+            status_code=status_code, content=model.model_dump(by_alias=True, exclude_none=True)
+        )
+
+    @staticmethod
+    def _etag(payload: dict[str, Any]) -> str:
+        digest = hashlib.sha256(
+            json.dumps(payload, sort_keys=True, default=str).encode()
+        ).hexdigest()
+        return f'"{digest[:16]}"'

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/schemas/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from .bulk_evaluation_request import BulkEvaluationRequest
+from .bulk_evaluation_success import BulkEvaluationSuccess
+from .evaluation_failure import EvaluationFailure
+from .evaluation_request import EvaluationRequest
+from .evaluation_success import EvaluationSuccess
+from .flag_not_found import FlagNotFound
+
+__all__ = [
+    "EvaluationRequest",
+    "BulkEvaluationRequest",
+    "EvaluationSuccess",
+    "EvaluationFailure",
+    "FlagNotFound",
+    "BulkEvaluationSuccess",
+]

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/schemas/bulk_evaluation_request.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class BulkEvaluationRequest(BaseModel):
+    """Body of a bulk evaluation request (static context for all flags)."""
+
+    context: dict[str, Any] = Field(default_factory=dict)

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/schemas/bulk_evaluation_success.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from pydantic import BaseModel
+
+from fast_feature.core import EvaluationOutcome
+
+from .evaluation_failure import EvaluationFailure
+from .evaluation_success import EvaluationSuccess
+
+
+class BulkEvaluationSuccess(BaseModel):
+    """The bulk evaluation response: a mix of per-flag successes and failures."""
+
+    flags: list[EvaluationSuccess | EvaluationFailure]
+    metadata: dict[str, Any] | None = None
+
+    @classmethod
+    def from_outcomes(cls, outcomes: Iterable[EvaluationOutcome]) -> BulkEvaluationSuccess:
+        flags: list[EvaluationSuccess | EvaluationFailure] = []
+        for outcome in outcomes:
+            if outcome.is_error:
+                flags.append(EvaluationFailure.from_outcome(outcome))
+            else:
+                flags.append(EvaluationSuccess.from_outcome(outcome))
+        return cls(flags=flags)

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/schemas/evaluation_failure.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from fast_feature.core import ErrorCode, EvaluationOutcome
+
+
+class EvaluationFailure(BaseModel):
+    """A failed flag evaluation, per the OFREP contract."""
+
+    key: str
+    error_code: str = Field(serialization_alias="errorCode")
+    error_details: str | None = Field(default=None, serialization_alias="errorDetails")
+
+    @classmethod
+    def from_outcome(cls, outcome: EvaluationOutcome) -> EvaluationFailure:
+        code = outcome.error_code or ErrorCode.GENERAL
+        return cls(key=outcome.key, error_code=code.value, error_details=outcome.error_details)

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/schemas/evaluation_request.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class EvaluationRequest(BaseModel):
+    """Body of a single-flag evaluation request."""
+
+    context: dict[str, Any] = Field(default_factory=dict)

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/schemas/evaluation_success.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from fast_feature.core import EvaluationOutcome
+
+
+class EvaluationSuccess(BaseModel):
+    """A successful flag evaluation, per the OFREP contract."""
+
+    key: str
+    reason: str
+    value: Any = None
+    variant: str | None = None
+    metadata: dict[str, Any] | None = None
+
+    @classmethod
+    def from_outcome(cls, outcome: EvaluationOutcome) -> EvaluationSuccess:
+        return cls(
+            key=outcome.key,
+            reason=outcome.reason.value,
+            value=outcome.value,
+            variant=outcome.variant,
+            metadata=outcome.metadata,
+        )

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/schemas/flag_not_found.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from fast_feature.core import ErrorCode, EvaluationOutcome
+
+
+class FlagNotFound(BaseModel):
+    """The 404 body returned when a flag key does not exist."""
+
+    key: str
+    error_code: str = Field(default=ErrorCode.FLAG_NOT_FOUND.value, serialization_alias="errorCode")
+    error_details: str | None = Field(default=None, serialization_alias="errorDetails")
+
+    @classmethod
+    def from_outcome(cls, outcome: EvaluationOutcome) -> FlagNotFound:
+        return cls(key=outcome.key, error_details=outcome.error_details)

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/service/__init__.py

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

fast_feature_ofrep-0.0.1/src/fast_feature/ofrep/service/evaluation_service.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from fast_feature.core import (
+    CoreError,
+    ErrorCode,
+    EvaluationContext,
+    EvaluationOutcome,
+    Flag,
+    FlagRepository,
+)
+from fast_feature.engine import TargetingEngine
+
+from ..errors import OfrepError
+
+
+class EvaluationService:
+    """Orchestrates the repository and the targeting engine for OFREP."""
+
+    def __init__(
+        self, repository: FlagRepository, *, engine: TargetingEngine | None = None
+    ) -> None:
+        self._repository = repository
+        self._engine = engine or TargetingEngine()
+
+    async def evaluate(
+        self, key: str, context: EvaluationContext | None = None
+    ) -> EvaluationOutcome:
+        flag = await self._load(key)
+        if flag is None:
+            return EvaluationOutcome.error(
+                key, ErrorCode.FLAG_NOT_FOUND, f"Flag {key!r} was not found"
+            )
+        return self._engine.evaluate(flag, context)
+
+    async def evaluate_all(
+        self, context: EvaluationContext | None = None
+    ) -> list[EvaluationOutcome]:
+        try:
+            flags = await self._repository.list_all()
+        except CoreError as exc:
+            raise OfrepError("failed to list flags") from exc
+        return [self._engine.evaluate(flag, context) for flag in flags]
+
+    async def _load(self, key: str) -> Flag | None:
+        try:
+            return await self._repository.get(key)
+        except CoreError as exc:
+            raise OfrepError(f"failed to load flag {key!r}") from exc