interloper-api 0.99.0__tar.gz → 0.101.0__tar.gz

{interloper_api-0.99.0 → interloper_api-0.101.0}/PKG-INFO

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

{interloper_api-0.99.0 → interloper_api-0.101.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "interloper-api"
-version = "0.99.0"
+version = "0.101.0"
 description = "Interloper FastAPI routes"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -53,6 +53,7 @@ extend-select = [
     "ANN202",
     "DOC",
     "D",
+    "TID251",
 ]
 
 [tool.ruff.lint.pydocstyle]
@@ -71,12 +72,22 @@ extend-immutable-calls = [
     "fastapi.Security",
 ]
 
+[tool.ruff.lint.flake8-tidy-imports.banned-api.sqlalchemy]
+msg = "Database access goes through interloper_db.Store facets"
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api.sqlmodel]
+msg = "Database access goes through interloper_db.Store facets"
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api."interloper_db.session"]
+msg = "Database access goes through interloper_db.Store facets"
+
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = [
     "F401",
     "F403",
 ]
 "tests/**" = [
+    "TID251",
     "ANN",
     "F811",
     "D101",

{interloper_api-0.99.0 → interloper_api-0.101.0}/pyproject.toml.orig

@@ -3,7 +3,7 @@
 # ###############
 [project]
 name = "interloper-api"
-version = "0.99.0"
+version = "0.101.0"
 description = "Interloper FastAPI routes"
 readme = "README.md"
 authors = [{ name = "Guillaume Onfroy", email = "guillaume@digitlcloud.com" }]
@@ -43,7 +43,7 @@ line-length = 120
 
 [tool.ruff.lint]
 preview = true
-extend-select = ["E", "I", "UP", "ANN001", "ANN201", "ANN202", "DOC", "D"]
+extend-select = ["E", "I", "UP", "ANN001", "ANN201", "ANN202", "DOC", "D", "TID251"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
@@ -63,6 +63,13 @@ extend-immutable-calls = [
     "fastapi.Security",
 ]
 
+# Raw database access lives in interloper-db alone; this package reads and
+# writes through the store's facets.
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"sqlalchemy".msg = "Database access goes through interloper_db.Store facets"
+"sqlmodel".msg = "Database access goes through interloper_db.Store facets"
+"interloper_db.session".msg = "Database access goes through interloper_db.Store facets"
+
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401", "F403"]
-"tests/**" = ["ANN", "F811", "D101", "D102", "D103", "D104", "D107", "RUF069", "PLW0108"]
+"tests/**" = ["TID251", "ANN", "F811", "D101", "D102", "D103", "D104", "D107", "RUF069", "PLW0108"]

{interloper_api-0.99.0 → interloper_api-0.101.0}/src/interloper_api/app.py

@@ -10,7 +10,15 @@ 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, HydrationError, NotFoundError, QuotaExceededError
+from interloper.errors import (
+    ComponentDriftError,
+    ConfigError,
+    ConflictError,
+    HydrationError,
+    InUseError,
+    NotFoundError,
+    QuotaExceededError,
+)
 from interloper_db import Store
 
 from interloper_api.dependencies import (
@@ -28,10 +36,12 @@ from interloper_api.routes import (
     auth,
     backfills,
     components,
+    executions,
     health,
     oauth,
     organisations,
     overview,
+    relations,
     runs,
     tokens,
     websocket,
@@ -48,7 +58,9 @@ _ROUTE_MODULES: tuple[ModuleType, ...] = (
     admin,
     catalog_routes,
     components,
+    relations,
     runs,
+    executions,
     backfills,
     overview,
     oauth,
@@ -61,52 +73,48 @@ _ROUTE_MODULES: tuple[ModuleType, ...] = (
 # -- 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)})
-
+#: Framework errors that have an HTTP meaning, by the status each answers.
+#: Drift and an unhydratable record are 409s: the record stays broken until a
+#: user repoints, re-keys or rewrites it, so the reason is surfaced instead of
+#: an opaque 500. Anything absent here is a bug and stays a 500.
+_ERROR_STATUS: dict[type[Exception], int] = {
+    ConfigError: 400,
+    NotFoundError: 404,
+    ConflictError: 409,
+    ComponentDriftError: 409,
+    HydrationError: 409,
+}
 
-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.
+async def _plain_error(_request: Request, exception: Exception) -> JSONResponse:
+    """Render a framework error as its mapped status, the message as ``detail``.
 
     Args:
         _request: The incoming request, unused.
-        exception: The raised :class:`ComponentDriftError`.
+        exception: The raised error, an instance of exactly one key of
+            :data:`_ERROR_STATUS` (none of the keys subclasses another).
 
     Returns:
-        A 409 response carrying the exception message as ``detail``.
+        The response, at the status mapped to the error's class.
     """
-    return JSONResponse(status_code=409, content={"detail": str(exception)})
-
+    status = next(status for error_type, status in _ERROR_STATUS.items() if isinstance(exception, error_type))
+    return JSONResponse(status_code=status, content={"detail": str(exception)})
 
-async def _hydration_failed(_request: Request, exception: HydrationError) -> JSONResponse:
-    """Render an unreadable stored record as a conflict rather than a 500.
 
-    A record that cannot be rebuilt from the database (a payload the active
-    ``INTERLOPER_ENCRYPTION_KEY`` cannot decrypt, a stored config the class no
-    longer accepts) stays broken until an operator re-keys or rewrites it, so
-    like drift it surfaces as a 409 carrying the reason instead of an opaque
-    500 that only the server log explains.
+async def _in_use(_request: Request, exception: InUseError) -> JSONResponse:
+    """Render a refused deletion as a 409 naming what still depends on the record.
 
     Args:
         _request: The incoming request, unused.
-        exception: The raised :class:`HydrationError`.
+        exception: The raised :class:`InUseError`.
 
     Returns:
-        A 409 response carrying the exception message as ``detail``.
+        A 409 response whose ``detail`` carries the message and the referrers
+        as ``used_by``.
     """
-    return JSONResponse(status_code=409, content={"detail": str(exception)})
+    return JSONResponse(
+        status_code=409, content={"detail": {"message": str(exception), "used_by": exception.referrers}}
+    )
 
 
 async def _quota_exceeded(_request: Request, exception: QuotaExceededError) -> JSONResponse:
@@ -133,16 +141,28 @@ async def _quota_exceeded(_request: Request, exception: QuotaExceededError) -> J
     )
 
 
-#: 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,
-    HydrationError: _hydration_failed,
+#: Errors whose response carries more than the message.
+_STRUCTURED_ERRORS: dict[type[Exception], Any] = {
+    InUseError: _in_use,
     QuotaExceededError: _quota_exceeded,
 }
 
 
+def install_error_handlers(app: FastAPI) -> None:
+    """Answer every framework error that has an HTTP meaning with its status.
+
+    Routes raise the store's errors as they come; this one mapping turns them
+    into responses, so no handler translates an exception by hand.
+
+    Args:
+        app: The application to install the handlers on.
+    """
+    for error_type in _ERROR_STATUS:
+        app.add_exception_handler(error_type, _plain_error)
+    for error_type, handler in _STRUCTURED_ERRORS.items():
+        app.add_exception_handler(error_type, handler)
+
+
 # -- Application factory -------------------------------------------------------
 
 
@@ -172,8 +192,7 @@ def create_app(
     """
     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)
+    install_error_handlers(app)
 
     if cors_origins:
         app.add_middleware(

{interloper_api-0.99.0 → interloper_api-0.101.0}/src/interloper_api/dependencies/__init__.py

@@ -8,6 +8,7 @@ organisation per request; ``rbac`` gates handlers on the caller's role.
 from interloper_api.dependencies.auth import (
     CurrentUserDep,
     OrgIdDep,
+    SessionContextDep,
     get_current_org,
     get_current_user,
     get_org_id,
@@ -19,6 +20,7 @@ from interloper_api.dependencies.rbac import (
     SuperAdminDep,
     ViewerDep,
     authorize_org_member,
+    authorize_organisation,
     load_authorized,
     require_admin,
     require_editor,
@@ -60,10 +62,12 @@ __all__ = [
     "EditorDep",
     "OrgIdDep",
     "QuotaDefaultsDep",
+    "SessionContextDep",
     "StoreDep",
     "SuperAdminDep",
     "ViewerDep",
     "authorize_org_member",
+    "authorize_organisation",
     "get_admin_config",
     "get_agent",
     "get_auth_config",

{interloper_api-0.99.0 → interloper_api-0.101.0}/src/interloper_api/dependencies/auth.py

@@ -12,86 +12,64 @@ from interloper_db.models import AuthSession
 from interloper_api.dependencies.state import get_store
 
 
-def get_current_user(
+def get_session_context(
     store: Store = Depends(get_store),
     session_token: str | None = Cookie(default=None),
-) -> Profile:
-    """Resolve the current user from the session cookie.
+) -> tuple[Profile, AuthSession]:
+    """Resolve the caller and their login session from the session cookie.
 
     Args:
         store: The Store instance.
         session_token: Session cookie value.
 
     Returns:
-        The authenticated Profile.
+        ``(Profile, AuthSession)``.
 
     Raises:
-        HTTPException: 401 if not authenticated or session invalid/expired.
+        HTTPException: 401 if not authenticated or the session is invalid or expired.
     """
     if not session_token:
         raise HTTPException(status_code=401, detail="Not authenticated")
-
-    result = store.auth.resolve_session(session_token)
+    result = store.sessions.resolve(session_token)
     if not result:
         raise HTTPException(status_code=401, detail="Invalid or expired session")
-
-    profile, _ = result
-    return profile
+    return result
 
 
-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.
+def get_current_user(
+    context: tuple[Profile, AuthSession] = Depends(get_session_context),
+) -> Profile:
+    """Resolve the current user from the session.
 
     Args:
-        store: The Store instance.
-        session_token: Session cookie value.
+        context: The caller and their session.
 
     Returns:
-        ``(Profile, Session)`` tuple.
-
-    Raises:
-        HTTPException: 401 if not authenticated.
+        The authenticated Profile.
     """
-    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
+    profile, _ = context
+    return profile
 
 
 def get_current_org(
+    context: tuple[Profile, AuthSession] = Depends(get_session_context),
     store: Store = Depends(get_store),
-    session_token: str | None = Cookie(default=None),
 ) -> Organisation:
-    """Resolve the current organisation from the session.
+    """Resolve the organisation the session is working in.
 
     Args:
+        context: The caller and their session.
         store: The Store instance.
-        session_token: Session cookie value.
 
     Returns:
         The active Organisation.
 
     Raises:
-        HTTPException: 400 if no organisation selected, 401 if not authenticated.
+        HTTPException: 400 if no organisation is selected.
     """
-    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
+    _, session_row = context
     if not session_row.organisation_id:
         raise HTTPException(status_code=400, detail="No organisation selected")
-
     return store.organisations.get(session_row.organisation_id)
 
 
@@ -112,4 +90,5 @@ def get_org_id(
 # -- Dependency aliases --------------------------------------------------------
 
 CurrentUserDep = Annotated[Profile, Depends(get_current_user)]
+SessionContextDep = Annotated[tuple[Profile, AuthSession], Depends(get_session_context)]
 OrgIdDep = Annotated[UUID, Depends(get_org_id)]

{interloper_api-0.99.0 → interloper_api-0.101.0}/src/interloper_api/dependencies/rbac.py

@@ -8,13 +8,11 @@ from uuid import UUID
 
 from fastapi import Depends, HTTPException
 from interloper.errors import NotFoundError
-from interloper_db import Profile, Store
+from interloper_db import Profile, Role, Store
 
 from interloper_api.dependencies.auth import get_current_user, get_org_id
 from interloper_api.dependencies.state import get_store
 
-_ROLE_RANK = {"viewer": 0, "editor": 1, "admin": 2}
-
 
 def authorize_org_member(
     user: Profile,
@@ -43,13 +41,33 @@ def authorize_org_member(
     Raises:
         HTTPException: 404 if not a member, 403 if the role is insufficient.
     """
-    role = store.organisations.member_role(user.id, org_id)
+    role = store.members.role(org_id, user.id)
     if role is None:
         raise HTTPException(status_code=404, detail=detail)
-    if _ROLE_RANK.get(role, -1) < _ROLE_RANK[minimum]:
+    if not Role.at_least(role, minimum):
         raise HTTPException(status_code=403, detail=f"Requires {minimum} role or higher")
 
 
+def authorize_organisation(user: Profile, org_id: UUID, store: Store, *, minimum: str = "viewer") -> None:
+    """Authorize an organisation-addressed route: a member holding *minimum*, or a super-admin.
+
+    The organisation routes take the organisation from the path, so they serve
+    its own members and the platform's super-admins through one set of
+    endpoints. A super-admin passes on any live organisation; anyone else must
+    be a member, a non-member reading as a missing organisation.
+
+    Args:
+        user: The authenticated user.
+        org_id: The organisation the path addresses.
+        store: The Store instance.
+        minimum: Minimum role a member needs (``viewer``, ``editor``, ``admin``).
+    """
+    if user.is_super_admin:
+        store.organisations.get(org_id)
+        return
+    authorize_org_member(user, org_id, store, minimum=minimum, detail=f"Organisation {org_id} not found")
+
+
 def load_authorized(
     fetch: Callable[[UUID], Any],
     entity_id: UUID,
@@ -109,10 +127,10 @@ def _check_role(
     Raises:
         HTTPException: 403 if insufficient permissions.
     """
-    role = store.organisations.member_role(user.id, org_id)
+    role = store.members.role(org_id, user.id)
     if role is None:
         raise HTTPException(status_code=403, detail="Not a member of this organisation")
-    if _ROLE_RANK.get(role, -1) < _ROLE_RANK[minimum]:
+    if not Role.at_least(role, minimum):
         raise HTTPException(status_code=403, detail=f"Requires {minimum} role or higher")
     return user
 

interloper_api-0.101.0/src/interloper_api/notifications/__init__.py

@@ -0,0 +1,7 @@
+"""Outbound notifications the API sends on a user's behalf."""
+
+from interloper_api.notifications.base import Email
+from interloper_api.notifications.invitations import InvitationEmail
+from interloper_api.notifications.super_admins import SuperAdminPromotionEmail
+
+__all__ = ["Email", "InvitationEmail", "SuperAdminPromotionEmail"]