interloper-api 0.65.1__tar.gz → 0.67.0__tar.gz

{interloper_api-0.65.1 → interloper_api-0.67.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: interloper-api
-Version: 0.65.1
+Version: 0.67.0
 Summary: Interloper FastAPI routes
 Author: Guillaume Onfroy
 Author-email: Guillaume Onfroy <guillaume@digitlcloud.com>

{interloper_api-0.65.1 → interloper_api-0.67.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "interloper-api"
-version = "0.65.1"
+version = "0.67.0"
 description = "Interloper FastAPI routes"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -43,6 +43,7 @@ workspace = true
 line-length = 120
 
 [tool.ruff.lint]
+preview = true
 extend-select = [
     "E",
     "I",
@@ -50,6 +51,24 @@ extend-select = [
     "ANN001",
     "ANN201",
     "ANN202",
+    "DOC",
+    "D",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = [
+    "fastapi.Body",
+    "fastapi.Cookie",
+    "fastapi.Depends",
+    "fastapi.File",
+    "fastapi.Form",
+    "fastapi.Header",
+    "fastapi.Path",
+    "fastapi.Query",
+    "fastapi.Security",
 ]
 
 [tool.ruff.lint.per-file-ignores]
@@ -60,4 +79,9 @@ extend-select = [
 "tests/**" = [
     "ANN",
     "F811",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "D107",
 ]

{interloper_api-0.65.1 → interloper_api-0.67.0}/pyproject.toml.orig

@@ -3,7 +3,7 @@
 # ###############
 [project]
 name = "interloper-api"
-version = "0.65.1"
+version = "0.67.0"
 description = "Interloper FastAPI routes"
 readme = "README.md"
 authors = [{ name = "Guillaume Onfroy", email = "guillaume@digitlcloud.com" }]
@@ -42,8 +42,27 @@ interloper-agent = { workspace = true }
 line-length = 120
 
 [tool.ruff.lint]
-extend-select = ["E", "I", "UP", "ANN001", "ANN201", "ANN202"]
+preview = true
+extend-select = ["E", "I", "UP", "ANN001", "ANN201", "ANN202", "DOC", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+# FastAPI's whole dependency-injection surface is calls in argument defaults;
+# B008 exists for mutable defaults, which these are not.
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = [
+    "fastapi.Body",
+    "fastapi.Cookie",
+    "fastapi.Depends",
+    "fastapi.File",
+    "fastapi.Form",
+    "fastapi.Header",
+    "fastapi.Path",
+    "fastapi.Query",
+    "fastapi.Security",
+]
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401", "F403"]
-"tests/**" = ["ANN", "F811"]
+"tests/**" = ["ANN", "F811", "D101", "D102", "D103", "D104", "D107"]

interloper_api-0.67.0/src/interloper_api/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP API for interloper: catalog, collection, run, and auth endpoints."""
+
+from interloper_api.app import create_app
+
+__all__ = ["create_app"]

interloper_api-0.67.0/src/interloper_api/app.py

@@ -0,0 +1,241 @@
+"""FastAPI application factory for the interloper API."""
+
+from __future__ import annotations
+
+import logging
+from types import ModuleType
+from typing import Any
+
+from fastapi import APIRouter, FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from interloper.catalog.base import Catalog
+from interloper.errors import ComponentDriftError, NotFoundError, QuotaExceededError
+from interloper_db import Store
+
+from interloper_api.dependencies import (
+    set_admin_config,
+    set_auth_config,
+    set_catalog,
+    set_features,
+    set_quota_defaults,
+    set_smtp_config,
+    set_store,
+)
+from interloper_api.routes import (
+    admin,
+    auth,
+    backfills,
+    components,
+    health,
+    oauth,
+    organisations,
+    runs,
+    tokens,
+    websocket,
+)
+from interloper_api.routes import catalog as catalog_routes
+
+logger = logging.getLogger(__name__)
+
+#: Routers mounted under ``/api`` for every deployment. The agent router is
+#: absent by design: it is optional and mounted by :func:`_mount_agent`.
+_ROUTE_MODULES: tuple[ModuleType, ...] = (
+    auth,
+    organisations,
+    admin,
+    catalog_routes,
+    components,
+    runs,
+    backfills,
+    oauth,
+    tokens,
+    websocket,
+    health,
+)
+
+
+# -- Error handling ------------------------------------------------------------
+
+
+async def _not_found(_request: Request, exception: NotFoundError) -> JSONResponse:
+    """Render a missing store target as a plain 404.
+
+    Args:
+        _request: The incoming request, unused.
+        exception: The raised :class:`NotFoundError`.
+
+    Returns:
+        A 404 response carrying the exception message as ``detail``.
+    """
+    return JSONResponse(status_code=404, content={"detail": str(exception)})
+
+
+async def _component_drift(_request: Request, exception: ComponentDriftError) -> JSONResponse:
+    """Render catalog drift as a conflict rather than a 500.
+
+    Hydrating or running a drifted source/asset cannot succeed until the user
+    resolves the drift, so it surfaces as a clean 409 the UI can act on.
+
+    Args:
+        _request: The incoming request, unused.
+        exception: The raised :class:`ComponentDriftError`.
+
+    Returns:
+        A 409 response carrying the exception message as ``detail``.
+    """
+    return JSONResponse(status_code=409, content={"detail": str(exception)})
+
+
+async def _quota_exceeded(_request: Request, exception: QuotaExceededError) -> JSONResponse:
+    """Render store-level quota enforcement as a 429 with structured context.
+
+    Args:
+        _request: The incoming request, unused.
+        exception: The raised :class:`QuotaExceededError`.
+
+    Returns:
+        A 429 response whose ``detail`` carries the message plus the quota
+        name, its limit, and the amount already used.
+    """
+    return JSONResponse(
+        status_code=429,
+        content={
+            "detail": {
+                "message": str(exception),
+                "quota": exception.quota,
+                "limit": exception.limit,
+                "used": exception.used,
+            }
+        },
+    )
+
+
+#: Framework errors that have an HTTP meaning, and the response each becomes.
+#: Anything absent here is a bug and stays a 500.
+_ERROR_HANDLERS: dict[type[Exception], Any] = {
+    NotFoundError: _not_found,
+    ComponentDriftError: _component_drift,
+    QuotaExceededError: _quota_exceeded,
+}
+
+
+# -- Application factory -------------------------------------------------------
+
+
+def create_app(
+    store: Store | None = None,
+    catalog: Catalog | None = None,
+    settings: Any | None = None,
+    cors_origins: list[str] | None = None,
+    **kwargs: Any,
+) -> FastAPI:
+    """Create the FastAPI application with all routes.
+
+    Args:
+        store: The ``Store`` instance for persistence.
+        catalog: Catalog instance.
+        settings: Full ``AppSettings``; the factory slices what it needs
+            (auth, smtp, agent) and builds the secrets-redacted snapshot for
+            the super-admin ``/admin/config`` view. The agent routes mount
+            only when enabled (or with no settings) and the ``agent`` extra
+            is installed.
+        cors_origins: Allowed CORS origins. Only needed in dev mode for direct
+            WebSocket connections that bypass the Vite proxy.
+        **kwargs: Additional kwargs forwarded to ``FastAPI()``.
+
+    Returns:
+        The configured FastAPI application.
+    """
+    app = FastAPI(title="Interloper API", lifespan=websocket.realtime_lifespan, **kwargs)
+
+    for error_type, handler in _ERROR_HANDLERS.items():
+        app.add_exception_handler(error_type, handler)
+
+    if cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cors_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    api = APIRouter(prefix="/api")
+    for module in _ROUTE_MODULES:
+        api.include_router(module.router)
+    agent_available = _mount_agent(api, settings)
+    app.include_router(api)
+
+    # After mounting, so the feature flag and the config snapshot can record
+    # whether the agent actually mounted. Routes read state per request, never
+    # at mount time, so the order is safe.
+    _install_state(store, catalog, settings, agent_available=agent_available)
+
+    oauth.log_provider_status()
+
+    return app
+
+
+# -- Internals -----------------------------------------------------------------
+
+
+def _mount_agent(api: APIRouter, settings: Any | None) -> bool:
+    """Mount the optional agent routes, reporting whether they are available.
+
+    Args:
+        api: The ``/api`` router to mount onto.
+        settings: Full ``AppSettings``, or ``None`` to mount whenever the
+            extra is installed.
+
+    Returns:
+        True when the agent routes are mounted.
+    """
+    if settings is not None and not settings.agent.enabled:
+        logger.info("Agent routes not mounted: disabled via settings.")
+        return False
+
+    try:
+        from interloper_api.routes import agent as agent_routes
+    except ImportError:
+        logger.warning(
+            "Agent routes not mounted: the 'agent' extra is not installed "
+            "(install interloper-api[agent]); /agent endpoints will return 404."
+        )
+        return False
+
+    api.include_router(agent_routes.router)
+    return True
+
+
+def _install_state(
+    store: Store | None,
+    catalog: Catalog | None,
+    settings: Any | None,
+    *,
+    agent_available: bool,
+) -> None:
+    """Install the process-wide state the request dependencies read back.
+
+    Args:
+        store: The ``Store`` instance, or ``None`` to leave it unset.
+        catalog: Catalog instance, or ``None`` to leave it unset.
+        settings: Full ``AppSettings``, or ``None`` to install neither the
+            settings slices nor the admin config snapshot.
+        agent_available: Whether the agent routes mounted, recorded as a
+            feature flag and in the admin config snapshot.
+    """
+    if store:
+        set_store(store)
+    if catalog:
+        set_catalog(catalog)
+
+    set_features({"agent": agent_available})
+
+    if settings:
+        set_auth_config(settings.auth)
+        set_smtp_config(settings.smtp)
+        set_quota_defaults(settings.quota)
+        set_admin_config(
+            admin.AdminConfigResponse.from_settings(settings, features={"agent": agent_available}, catalog=catalog)
+        )

interloper_api-0.67.0/src/interloper_api/dependencies/__init__.py

@@ -0,0 +1,64 @@
+"""Shared FastAPI dependencies: application state, identity, and role gates.
+
+Three concerns, one import surface. ``state`` holds what ``create_app``
+installs once at startup; ``auth`` resolves the caller and their active
+organisation per request; ``rbac`` gates handlers on the caller's role.
+"""
+
+from interloper_api.dependencies.auth import (
+    get_current_org,
+    get_current_user,
+    get_org_id,
+    get_session_context,
+)
+from interloper_api.dependencies.rbac import (
+    authorize_org_member,
+    load_authorized,
+    require_admin,
+    require_editor,
+    require_super_admin,
+    require_viewer,
+)
+from interloper_api.dependencies.state import (
+    get_admin_config,
+    get_auth_config,
+    get_catalog,
+    get_features,
+    get_quota_defaults,
+    get_smtp_config,
+    get_store,
+    set_admin_config,
+    set_auth_config,
+    set_catalog,
+    set_features,
+    set_quota_defaults,
+    set_smtp_config,
+    set_store,
+)
+
+__all__ = [
+    "authorize_org_member",
+    "get_admin_config",
+    "get_auth_config",
+    "get_catalog",
+    "get_current_org",
+    "get_current_user",
+    "get_features",
+    "get_org_id",
+    "get_quota_defaults",
+    "get_session_context",
+    "get_smtp_config",
+    "get_store",
+    "load_authorized",
+    "require_admin",
+    "require_editor",
+    "require_super_admin",
+    "require_viewer",
+    "set_admin_config",
+    "set_auth_config",
+    "set_catalog",
+    "set_features",
+    "set_quota_defaults",
+    "set_smtp_config",
+    "set_store",
+]

interloper_api-0.67.0/src/interloper_api/dependencies/auth.py

@@ -0,0 +1,108 @@
+"""Request-scoped identity: who is calling, and which organisation they are in."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import Cookie, Depends, HTTPException
+from interloper_db import Organisation, Profile, Store
+from interloper_db.models import AuthSession
+
+from interloper_api.dependencies.state import get_store
+
+
+def get_current_user(
+    store: Store = Depends(get_store),
+    session_token: str | None = Cookie(default=None),
+) -> Profile:
+    """Resolve the current user from the session cookie.
+
+    Args:
+        store: The Store instance.
+        session_token: Session cookie value.
+
+    Returns:
+        The authenticated Profile.
+
+    Raises:
+        HTTPException: 401 if not authenticated or session invalid/expired.
+    """
+    if not session_token:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+
+    result = store.auth.resolve_session(session_token)
+    if not result:
+        raise HTTPException(status_code=401, detail="Invalid or expired session")
+
+    profile, _ = result
+    return profile
+
+
+def get_session_context(
+    store: Store = Depends(get_store),
+    session_token: str | None = Cookie(default=None),
+) -> tuple[Profile, AuthSession]:
+    """Resolve user and session from the cookie.
+
+    Args:
+        store: The Store instance.
+        session_token: Session cookie value.
+
+    Returns:
+        ``(Profile, Session)`` tuple.
+
+    Raises:
+        HTTPException: 401 if not authenticated.
+    """
+    if not session_token:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+
+    result = store.auth.resolve_session(session_token)
+    if not result:
+        raise HTTPException(status_code=401, detail="Invalid or expired session")
+
+    return result
+
+
+def get_current_org(
+    store: Store = Depends(get_store),
+    session_token: str | None = Cookie(default=None),
+) -> Organisation:
+    """Resolve the current organisation from the session.
+
+    Args:
+        store: The Store instance.
+        session_token: Session cookie value.
+
+    Returns:
+        The active Organisation.
+
+    Raises:
+        HTTPException: 400 if no organisation selected, 401 if not authenticated.
+    """
+    if not session_token:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+
+    result = store.auth.resolve_session(session_token)
+    if not result:
+        raise HTTPException(status_code=401, detail="Invalid or expired session")
+
+    _, session_row = result
+    if not session_row.organisation_id:
+        raise HTTPException(status_code=400, detail="No organisation selected")
+
+    return store.organisations.get(session_row.organisation_id)
+
+
+def get_org_id(
+    org: Organisation = Depends(get_current_org),
+) -> UUID:
+    """Shorthand: return just the org UUID for route handlers.
+
+    Args:
+        org: The resolved Organisation.
+
+    Returns:
+        The organisation UUID.
+    """
+    return org.id