phlo-api 0.2.3__tar.gz → 0.3.0__tar.gz

{phlo_api-0.2.3 → phlo_api-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phlo-api
-Version: 0.2.3
+Version: 0.3.0
 Summary: Phlo API - Backend service exposing Phlo internals to Observatory
 Author-email: Phlo Team <team@phlo.dev>
 License: MIT

{phlo_api-0.2.3 → phlo_api-0.3.0}/README.md

@@ -20,6 +20,15 @@ phlo plugin install api
 | --------------- | --------- | --------------- |
 | `PHLO_API_PORT` | `4000`    | API server port |
 | `HOST`          | `0.0.0.0` | API server host |
+| `PHLO_AUTHORIZATION_BACKEND` | unset | Authorization backend capability name |
+| `PHLO_AUTHORIZATION_MODE` | `optional` | Guard behavior when no authorization backend exists |
+
+With `PHLO_AUTHORIZATION_MODE=optional`, guarded routes remain reachable until an
+authorization backend is configured. Set `PHLO_AUTHORIZATION_MODE=required` to
+fail closed with HTTP `503` on guarded routes when no backend is available.
+
+You can also declare these settings in `phlo.yaml` via `api.authorization` or
+`services.phlo-api.authorization`.
 
 ## Auto-Configuration
 

{phlo_api-0.2.3 → phlo_api-0.3.0}/pyproject.toml

@@ -19,7 +19,7 @@ dependencies = [
 description = "Phlo API - Backend service exposing Phlo internals to Observatory"
 name = "phlo-api"
 requires-python = ">=3.11"
-version = "0.2.3"
+version = "0.3.0"
 
 [[project.authors]]
 email = "team@phlo.dev"

phlo_api-0.3.0/src/phlo_api/__init__.py

@@ -0,0 +1,22 @@
+"""Phlo REST API package.
+
+This package provides the FastAPI-based REST API service for Phlo,
+exposing platform internals to the Observatory web application.
+
+Modules:
+    main: FastAPI application and core endpoints.
+    plugin: Service plugin registration for phlo-api.
+    api: Platform API routers (authentication, authorization, maintenance, observability).
+    observatory_api: Observatory-specific API routers (Dagster, Trino, Nessie, etc.).
+
+Example:
+    To start the API server locally:
+
+    .. code-block:: python
+
+        from phlo_api.main import app
+        import uvicorn
+
+        uvicorn.run(app, host="0.0.0.0", port=4000)
+
+"""

phlo_api-0.3.0/src/phlo_api/api/__init__.py

@@ -0,0 +1,20 @@
+"""Platform API routers exposed by phlo-api.
+
+This package contains core platform API routers for authentication,
+authorization, maintenance, and observability operations.
+
+Modules:
+    authentication: Authentication provider integration for FastAPI.
+    authorization: Authorization and permission checking.
+    maintenance: Iceberg maintenance observability endpoints.
+    observability: Platform health and metrics endpoints.
+
+Example:
+    Routers from this package are automatically registered by main.py:
+
+    .. code-block:: python
+
+        from phlo_api.api.maintenance import router as maintenance_router
+        app.include_router(maintenance_router, prefix="/api/maintenance")
+
+"""

{phlo_api-0.2.3 → phlo_api-0.3.0}/src/phlo_api/api/authentication.py

@@ -1,6 +1,33 @@
 """Authentication helpers for phlo-api.
 
 This module provides authentication capability integration for FastAPI routes.
+It bridges the phlo capabilities system with FastAPI request handling, enabling
+flexible authentication through pluggable providers.
+
+Key Functions:
+    get_authentication_provider: Resolve the configured authentication provider.
+    require_authentication_provider: Resolve provider or raise if unavailable.
+    authenticate_request: Authenticate a FastAPI request.
+    get_request_principal: Get the authenticated principal from a request.
+    require_principal: Get principal or raise HTTP 401.
+
+Environment Variables:
+    PHLO_AUTHENTICATION_PROVIDER: Name of the authentication provider to use.
+        Required when multiple providers are installed.
+
+Example:
+    Using authentication in a FastAPI route:
+
+    .. code-block:: python
+
+        from fastapi import Request
+        from phlo_api.api.authentication import require_principal
+
+        @app.get("/protected")
+        async def protected_route(request: Request):
+            principal = require_principal(request)
+            return {"user": principal.subject}
+
 """
 
 from __future__ import annotations
@@ -18,6 +45,7 @@ from phlo.capabilities import (
     list_capabilities,
     resolve_capability,
 )
+from phlo.infrastructure.config import get_authentication_provider_config
 from phlo.logging import get_logger
 
 logger = get_logger(__name__)
@@ -25,13 +53,34 @@ logger = get_logger(__name__)
 _AUTHENTICATION_PROVIDER_ENV = "PHLO_AUTHENTICATION_PROVIDER"
 
 
+def _configured_authentication_provider_name() -> str | None:
+    """Resolve the provider name from env first, then phlo.yaml."""
+    provider_name = os.environ.get(_AUTHENTICATION_PROVIDER_ENV)
+    if provider_name is not None:
+        normalized = provider_name.strip()
+        return normalized or None
+
+    return get_authentication_provider_config()
+
+
 def get_authentication_provider() -> AuthenticationProvider | None:
     """Resolve the authentication provider capability.
 
-    Returns None if no provider is configured.
-    Raises when multiple providers are installed without explicit selection.
+    Returns None if no provider is configured. Raises when multiple providers
+    are installed without explicit selection.
+
+    Args:
+        None: No arguments required.
+
+    Returns:
+        AuthenticationProvider instance, or None if not configured.
+
+    Raises:
+        RuntimeError: If the configured provider is not registered, or if multiple
+            providers are available without explicit selection.
+
     """
-    provider_name = os.environ.get(_AUTHENTICATION_PROVIDER_ENV)
+    provider_name = _configured_authentication_provider_name()
     result = resolve_capability("authentication_provider", provider_name)
     if provider_name and result is None:
         raise RuntimeError(
@@ -55,7 +104,18 @@ def get_authentication_provider() -> AuthenticationProvider | None:
 
 
 def require_authentication_provider() -> AuthenticationProvider:
-    """Resolve the authentication provider or raise if not available."""
+    """Resolve the authentication provider or raise if not available.
+
+    Args:
+        None: No arguments required.
+
+    Returns:
+        AuthenticationProvider instance.
+
+    Raises:
+        RuntimeError: If no authentication provider is configured.
+
+    """
     provider = get_authentication_provider()
     if provider is None:
         raise RuntimeError("Authentication provider not configured")
@@ -63,7 +123,21 @@ def require_authentication_provider() -> AuthenticationProvider:
 
 
 def create_request_context(request: Request) -> RequestContext:
-    """Create a RequestContext from a FastAPI request."""
+    """Create a RequestContext from a FastAPI request.
+
+    Extracts headers, cookies, query params, and connection metadata from
+    the incoming request for use by authentication providers.
+
+    Args:
+        request: The FastAPI request object.
+
+    Returns:
+        RequestContext populated with request metadata.
+
+    Raises:
+        None: No exceptions raised directly.
+
+    """
     headers_dict: dict[str, str] = {}
     for key, value in request.headers.items():
         headers_dict[key.lower()] = value
@@ -89,6 +163,16 @@ def authenticate_request(request: Request) -> AuthResult:
 
     Returns an AuthResult that indicates whether authentication succeeded.
     Caches the result in request.state to avoid duplicate authentication.
+
+    Args:
+        request: The FastAPI request object.
+
+    Returns:
+        AuthResult with authentication status and principal (if successful).
+
+    Raises:
+        None: No exceptions raised directly.
+
     """
     if hasattr(request.state, _AUTH_RESULT_CACHE_KEY):
         return request.state[_AUTH_RESULT_CACHE_KEY]
@@ -113,6 +197,16 @@ def get_request_principal(request: Request) -> AuthPrincipal | None:
 
     Returns None if no authentication provider is configured or authentication failed.
     Caches the result in request.state to avoid duplicate authentication.
+
+    Args:
+        request: The FastAPI request object.
+
+    Returns:
+        AuthPrincipal if authenticated, None otherwise.
+
+    Raises:
+        None: No exceptions raised directly.
+
     """
     if hasattr(request.state, _AUTH_PRINCIPAL_CACHE_KEY):
         return request.state[_AUTH_PRINCIPAL_CACHE_KEY]
@@ -133,6 +227,16 @@ def require_principal(request: Request) -> AuthPrincipal:
 
     Raises HTTPException 401 if authentication failed or no provider is configured.
     Uses cached result from request.state if available.
+
+    Args:
+        request: The FastAPI request object.
+
+    Returns:
+        AuthPrincipal if authentication succeeds.
+
+    Raises:
+        HTTPException: 401 if authentication fails or provider unavailable.
+
     """
     if hasattr(request.state, _AUTH_PRINCIPAL_CACHE_KEY):
         cached = request.state[_AUTH_PRINCIPAL_CACHE_KEY]
@@ -185,6 +289,16 @@ def optional_authenticate(request: Request) -> AuthPrincipal | None:
 
     Unlike require_principal, this does not raise on authentication failure.
     Useful for routes that have different behavior for authenticated vs anonymous.
+
+    Args:
+        request: The FastAPI request object.
+
+    Returns:
+        AuthPrincipal if authentication succeeds, None otherwise.
+
+    Raises:
+        None: No exceptions raised directly.
+
     """
     provider = get_authentication_provider()
     if provider is None:
@@ -200,7 +314,21 @@ def optional_authenticate(request: Request) -> AuthPrincipal | None:
 
 
 def get_capabilities_metadata() -> dict[str, Any]:
-    """Get metadata about available authentication capabilities."""
+    """Get metadata about available authentication capabilities.
+
+    Returns a dictionary with available providers, current provider setting,
+    and environment variable information.
+
+    Args:
+        None: No arguments required.
+
+    Returns:
+        Dictionary with authentication capability metadata.
+
+    Raises:
+        None: No exceptions raised directly.
+
+    """
     available_providers = list_capabilities("authentication_provider")
     current_provider = os.environ.get(_AUTHENTICATION_PROVIDER_ENV)