interloper-api 0.5.0__tar.gz → 0.7.0__tar.gz

{interloper_api-0.5.0 → interloper_api-0.7.0}/PKG-INFO

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

{interloper_api-0.5.0 → interloper_api-0.7.0}/pyproject.toml

@@ -3,7 +3,7 @@
 # ###############
 [project]
 name = "interloper-api"
-version = "0.5.0"
+version = "0.7.0"
 description = "Interloper FastAPI routes"
 readme = "README.md"
 authors = [{ name = "Guillaume Onfroy", email = "guillaume@digitlcloud.com" }]

{interloper_api-0.5.0 → interloper_api-0.7.0}/src/interloper_api/app.py

@@ -11,6 +11,7 @@ from interloper_db import Store
 
 from interloper_api.dependencies import set_auth_config, set_catalog, set_smtp_config, set_store
 from interloper_api.routes import (
+    admin,
     assets,
     auth,
     backfills,
@@ -72,6 +73,7 @@ def create_app(
     api = APIRouter(prefix="/api")
     api.include_router(auth.router, tags=["auth"])
     api.include_router(organisations.router, tags=["organisations"])
+    api.include_router(admin.router, tags=["admin"])
     api.include_router(catalog_routes.router, prefix="/catalog", tags=["catalog"])
     api.include_router(resources.router, prefix="/resources", tags=["resources"])
     api.include_router(sources.router, prefix="/sources", tags=["sources"])

{interloper_api-0.5.0 → interloper_api-0.7.0}/src/interloper_api/dependencies.py

@@ -291,3 +291,22 @@ def require_admin(
         HTTPException: 401/403 on auth or role failure.
     """
     return _check_role("admin", user, org_id, store)
+
+
+def require_super_admin(
+    user: Profile = Depends(get_current_user),
+) -> Profile:
+    """Require platform-wide super-admin privileges.
+
+    Unlike the org-scoped role dependencies, this is not bound to the session's
+    active organisation — it gates the cross-org admin surface.
+
+    Returns:
+        The authenticated Profile.
+
+    Raises:
+        HTTPException: 401 if not authenticated, 403 if not a super-admin.
+    """
+    if not user.is_super_admin:
+        raise HTTPException(status_code=403, detail="Requires super-admin privileges")
+    return user

interloper_api-0.7.0/src/interloper_api/routes/admin.py

@@ -0,0 +1,305 @@
+"""Super-admin routes — cross-organisation management.
+
+These endpoints are gated by :func:`require_super_admin` and are NOT bound to
+the session's active organisation. They let a platform super-admin manage every
+organisation's metadata, membership, and invitations. They deliberately grant
+no access to org-scoped *data* (sources, jobs, runs, …).
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from interloper_db import Profile, Store
+from pydantic import BaseModel
+
+from interloper_api.dependencies import get_store, require_super_admin
+from interloper_api.email import send_invite_email
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/admin", tags=["admin"])
+
+_ROLES = {"viewer", "editor", "admin"}
+
+
+# -- Response / Request models ------------------------------------------------
+
+
+class AdminOrganisationResponse(BaseModel):
+    """Organisation summary with member count for the admin surface."""
+
+    id: UUID
+    name: str
+    member_count: int
+    created_at: datetime | None = None
+
+
+class CreateOrganisationRequest(BaseModel):
+    """Request body for creating an organisation."""
+
+    name: str
+
+
+class UpdateOrganisationRequest(BaseModel):
+    """Request body for renaming an organisation."""
+
+    name: str
+
+
+class MemberResponse(BaseModel):
+    """Organisation member."""
+
+    id: UUID
+    email: str
+    name: str | None = None
+    avatar_url: str | None = None
+    role: str
+
+
+class UpdateRoleRequest(BaseModel):
+    """Request body for changing a member's role."""
+
+    role: str
+
+
+class InviteRequest(BaseModel):
+    """Request body for inviting a user."""
+
+    email: str
+    role: str = "viewer"
+
+
+class InvitationResponse(BaseModel):
+    """Pending invitation."""
+
+    id: UUID
+    email: str
+    role: str
+    created_at: datetime | None = None
+    expires_at: datetime
+
+
+# -- Helpers ------------------------------------------------------------------
+
+
+def _require_org(store: Store, org_id: UUID) -> object:
+    """Fetch an organisation or raise 404."""
+    org = store.get_organisation(org_id)
+    if not org:
+        raise HTTPException(status_code=404, detail="Organisation not found")
+    return org
+
+
+def _validate_role(role: str) -> str:
+    """Validate a role string or raise 400."""
+    if role not in _ROLES:
+        raise HTTPException(status_code=400, detail=f"Invalid role: {role}")
+    return role
+
+
+def _send_invitation_email(
+    request: Request,
+    invitation: object,
+    org_name: str,
+    inviter_name: str,
+) -> None:
+    """Send the invitation email if SMTP is configured, never failing the request."""
+    from interloper_api.dependencies import get_smtp_config
+
+    smtp_config = get_smtp_config()
+    if not smtp_config or not smtp_config.enabled:  # type: ignore[attr-defined]
+        return
+
+    token = invitation.token  # type: ignore[attr-defined]
+    email = invitation.email  # type: ignore[attr-defined]
+    base_url = str(request.base_url).rstrip("/")
+    invite_url = f"{base_url}/invite/{token}"
+
+    try:
+        send_invite_email(
+            smtp_config=smtp_config,
+            to=email,
+            org_name=org_name,
+            inviter_name=inviter_name,
+            invite_url=invite_url,
+        )
+    except Exception:
+        logger.exception("Failed to send invitation email to %s", email)
+
+
+# -- Organisations ------------------------------------------------------------
+
+
+@router.get("/organisations")
+def list_all_organisations(
+    user: Profile = Depends(require_super_admin),
+    store: Store = Depends(get_store),
+) -> list[AdminOrganisationResponse]:
+    """List every organisation with its member count."""
+    return [
+        AdminOrganisationResponse(
+            id=org.id,  # type: ignore[arg-type]
+            name=org.name,
+            member_count=count,
+            created_at=org.created_at,
+        )
+        for org, count in store.list_all_organisations()
+    ]
+
+
+@router.post("/organisations", status_code=201)
+def create_organisation(
+    body: CreateOrganisationRequest,
+    user: Profile = Depends(require_super_admin),
+    store: Store = Depends(get_store),
+) -> AdminOrganisationResponse:
+    """Create an organisation. The super-admin is not added as a member."""
+    org = store.create_organisation(name=body.name)
+    return AdminOrganisationResponse(
+        id=org.id,  # type: ignore[arg-type]
+        name=org.name,
+        member_count=0,
+        created_at=org.created_at,
+    )
+
+
+@router.patch("/organisations/{org_id}")
+def update_organisation(
+    org_id: UUID,
+    body: UpdateOrganisationRequest,
+    user: Profile = Depends(require_super_admin),
+    store: Store = Depends(get_store),
+) -> AdminOrganisationResponse:
+    """Rename an organisation."""
+    org = store.update_organisation(org_id, body.name)
+    if not org:
+        raise HTTPException(status_code=404, detail="Organisation not found")
+    members = store.list_org_members(org_id)
+    return AdminOrganisationResponse(
+        id=org.id,  # type: ignore[arg-type]
+        name=org.name,
+        member_count=len(members),
+        created_at=org.created_at,
+    )
+
+
+# -- Members ------------------------------------------------------------------
+
+
+@router.get("/organisations/{org_id}/members")
+def list_members(
+    org_id: UUID,
+    user: Profile = Depends(require_super_admin),
+    store: Store = Depends(get_store),
+) -> list[MemberResponse]:
+    """List all members of any organisation."""
+    _require_org(store, org_id)
+    members = store.list_org_members(org_id)
+    return [
+        MemberResponse(
+            id=profile.id,  # type: ignore[arg-type]
+            email=profile.email,
+            name=profile.name,
+            avatar_url=profile.avatar_url,
+            role=role,
+        )
+        for profile, role in members
+    ]
+
+
+@router.patch("/organisations/{org_id}/members/{user_id}")
+def update_member_role(
+    org_id: UUID,
+    user_id: UUID,
+    body: UpdateRoleRequest,
+    user: Profile = Depends(require_super_admin),
+    store: Store = Depends(get_store),
+) -> dict[str, str]:
+    """Change a member's role in any organisation."""
+    _validate_role(body.role)
+    if not store.update_member_role(org_id, user_id, body.role):
+        raise HTTPException(status_code=404, detail="Member not found")
+    return {"status": "ok"}
+
+
+@router.delete("/organisations/{org_id}/members/{user_id}")
+def remove_member(
+    org_id: UUID,
+    user_id: UUID,
+    user: Profile = Depends(require_super_admin),
+    store: Store = Depends(get_store),
+) -> dict[str, str]:
+    """Remove a member from any organisation."""
+    if not store.remove_org_member(org_id, user_id):
+        raise HTTPException(status_code=404, detail="Member not found")
+    return {"status": "ok"}
+
+
+# -- Invitations --------------------------------------------------------------
+
+
+@router.get("/organisations/{org_id}/invitations")
+def list_invitations(
+    org_id: UUID,
+    user: Profile = Depends(require_super_admin),
+    store: Store = Depends(get_store),
+) -> list[InvitationResponse]:
+    """List pending invitations for any organisation."""
+    _require_org(store, org_id)
+    return [
+        InvitationResponse(
+            id=inv.id,  # type: ignore[arg-type]
+            email=inv.email,
+            role=inv.role,
+            created_at=inv.created_at,
+            expires_at=inv.expires_at,
+        )
+        for inv in store.list_invitations(org_id)
+    ]
+
+
+@router.post("/organisations/{org_id}/invitations", status_code=201)
+def invite_member(
+    org_id: UUID,
+    body: InviteRequest,
+    request: Request,
+    user: Profile = Depends(require_super_admin),
+    store: Store = Depends(get_store),
+) -> InvitationResponse:
+    """Invite a user to any organisation by email."""
+    org = _require_org(store, org_id)
+    _validate_role(body.role)
+    invitation = store.create_invitation(
+        org_id=org_id,
+        email=body.email.strip(),
+        role=body.role,
+        invited_by=user.id,  # type: ignore[arg-type]
+    )
+
+    inviter_name = user.name or user.email
+    _send_invitation_email(request, invitation, org.name, inviter_name)  # type: ignore[attr-defined]
+
+    return InvitationResponse(
+        id=invitation.id,  # type: ignore[arg-type]
+        email=invitation.email,
+        role=invitation.role,
+        created_at=invitation.created_at,
+        expires_at=invitation.expires_at,
+    )
+
+
+@router.delete("/organisations/{org_id}/invitations/{invitation_id}")
+def cancel_invitation(
+    org_id: UUID,
+    invitation_id: UUID,
+    user: Profile = Depends(require_super_admin),
+    store: Store = Depends(get_store),
+) -> dict[str, str]:
+    """Cancel a pending invitation in any organisation."""
+    if not store.delete_invitation(invitation_id):
+        raise HTTPException(status_code=404, detail="Invitation not found")
+    return {"status": "ok"}

{interloper_api-0.5.0 → interloper_api-0.7.0}/src/interloper_api/routes/auth.py

@@ -37,6 +37,7 @@ class AuthUserResponse(BaseModel):
     name: str | None = None
     avatar_url: str | None = None
     role: str
+    is_super_admin: bool = False
     organisation: OrganisationResponse | None = None
     last_organisation_id: UUID | None = None
 
@@ -188,6 +189,7 @@ def get_me(
         name=profile.name,
         avatar_url=profile.avatar_url,
         role=role,
+        is_super_admin=profile.is_super_admin,
         organisation=OrganisationResponse.model_validate(org, from_attributes=True) if org else None,
         last_organisation_id=profile.last_organisation_id,
     )

{interloper_api-0.5.0 → interloper_api-0.7.0}/src/interloper_api/routes/runs.py

@@ -3,18 +3,24 @@
 from __future__ import annotations
 
 import datetime as dt
+from typing import Literal
 from uuid import UUID
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Response
 from interloper.errors import NotFoundError
 from interloper_db import Profile, Store
 from interloper_db.models import Event, Run
 from pydantic import BaseModel
 
-from interloper_api.dependencies import get_org_id, get_store, require_viewer
+from interloper_api.dependencies import get_org_id, get_store, require_editor, require_viewer
 
 router = APIRouter()
 
+#: Hard cap on the number of events returned in a single page, regardless of
+#: the requested ``limit``. Keeps a pathological ``?limit=1000000`` from loading
+#: an entire run's history into memory at once.
+MAX_EVENTS_PAGE_SIZE = 1000
+
 
 class RunResponse(BaseModel):
     """Response body for a run."""
@@ -25,11 +31,20 @@ class RunResponse(BaseModel):
     backfill_id: UUID | None
     partition_date: dt.date | None
     status: str
+    retry_of: UUID | None = None
+    attempt: int = 1
+    retry_scope: str | None = None
     started_at: str | None = None
     completed_at: str | None = None
     created_at: str | None = None
 
 
+class RetryRequest(BaseModel):
+    """Request body for retrying a failed run."""
+
+    scope: Literal["all", "failed"] = "all"
+
+
 class AssetExecutionResponse(BaseModel):
     """Response body for an asset execution (from the asset_executions view)."""
 
@@ -75,6 +90,9 @@ def _run_to_response(run: Run) -> RunResponse:
         backfill_id=run.backfill_id,
         partition_date=run.partition_date,
         status=run.status,
+        retry_of=run.retry_of,
+        attempt=run.attempt,
+        retry_scope=run.retry_scope,
         started_at=str(run.started_at) if run.started_at else None,
         completed_at=str(run.completed_at) if run.completed_at else None,
         created_at=str(run.created_at) if run.created_at else None,
@@ -107,6 +125,7 @@ def _event_to_response(event: Event) -> EventResponse:
 
 @router.get("/")
 def list_runs(
+    response: Response,
     job_id: UUID | None = None,
     backfill_id: UUID | None = None,
     status: str | None = None,
@@ -116,7 +135,13 @@ def list_runs(
     org_id: UUID = Depends(get_org_id),
     store: Store = Depends(get_store),
 ) -> list[RunResponse]:
-    """List runs with optional filters."""
+    """List runs with optional filters.
+
+    The total number of matching runs (ignoring ``limit``/``offset``) is
+    returned in the ``X-Total-Count`` response header so clients can paginate.
+    """
+    total = store.count_runs(org_id, job_id=job_id, backfill_id=backfill_id, status=status)
+    response.headers["X-Total-Count"] = str(total)
     runs = store.list_runs(
         org_id,
         job_id=job_id,
@@ -165,13 +190,49 @@ def list_asset_executions(
     ]
 
 
+@router.post("/{run_id}/retry")
+def retry_run(
+    run_id: UUID,
+    body: RetryRequest | None = None,
+    user: Profile = Depends(require_editor),
+    store: Store = Depends(get_store),
+) -> dict[str, str]:
+    """Queue a retry of a failed run.
+
+    Creates a new run linked to the original via ``retry_of``. With
+    ``scope="all"`` the whole DAG re-runs; with ``scope="failed"`` only the
+    previously failed/cancelled assets re-run.
+    """
+    scope = body.scope if body else "all"
+    try:
+        run = store.retry_run(run_id, scope=scope)
+    except NotFoundError:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+    except ValueError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+    return {"status": "queued", "run_id": str(run.id)}
+
+
 @router.get("/{run_id}/events")
 def list_run_events(
     run_id: UUID,
+    response: Response,
     limit: int = 100,
+    offset: int = 0,
     user: Profile = Depends(require_viewer),
     store: Store = Depends(get_store),
 ) -> list[EventResponse]:
-    """List events for a run."""
-    events = store.list_events(run_id=run_id, limit=limit)
+    """List events for a run, oldest first.
+
+    Events are ordered ``timestamp ASC`` and paged with ``limit``/``offset``.
+    The total number of events for the run (ignoring ``limit``/``offset``) is
+    returned in the ``X-Total-Count`` response header so clients can page
+    through every event — including the terminal/outcome events
+    (``asset_completed``, ``asset_failed``, ``run_failed``, …) that sort last.
+    """
+    limit = max(1, min(limit, MAX_EVENTS_PAGE_SIZE))
+    offset = max(0, offset)
+    total = store.count_events(run_id=run_id)
+    response.headers["X-Total-Count"] = str(total)
+    events = store.list_events(run_id=run_id, limit=limit, offset=offset)
     return [_event_to_response(e) for e in events]