interloper-api 0.2.0__tar.gz

interloper_api-0.2.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.3
+Name: interloper-api
+Version: 0.2.0
+Summary: Interloper FastAPI routes
+Author: Guillaume Onfroy
+Author-email: Guillaume Onfroy <guillaume@digitlcloud.com>
+Requires-Dist: interloper-core
+Requires-Dist: interloper-db
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: uvicorn[standard]>=0.41.0
+Requires-Dist: wsproto>=1.2.0
+Requires-Dist: interloper-agent ; extra == 'agent'
+Requires-Python: >=3.10
+Provides-Extra: agent
+Description-Content-Type: text/markdown
+

interloper_api-0.2.0/pyproject.toml

@@ -0,0 +1,53 @@
+# ###############
+# PROJECT / UV
+# ###############
+[project]
+name = "interloper-api"
+version = "0.2.0"
+description = "Interloper FastAPI routes"
+readme = "README.md"
+authors = [{ name = "Guillaume Onfroy", email = "guillaume@digitlcloud.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "interloper-core",
+    "interloper-db",
+    "fastapi>=0.115.0",
+    "httpx>=0.28.0",
+    "psycopg2-binary>=2.9.0",
+    "uvicorn[standard]>=0.41.0",
+    "wsproto>=1.2.0",
+]
+
+[project.optional-dependencies]
+agent = ["interloper-agent"]
+
+[build-system]
+requires = ["uv_build>=0.11.5,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+interloper-core = { workspace = true }
+interloper-db = { workspace = true }
+interloper-agent = { workspace = true }
+
+# ###############
+# RUFF
+# ###############
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+extend-select = ["E", "I", "UP", "ANN001", "ANN201", "ANN202"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "F403"]
+"tests/**" = ["ANN", "F811"]
+
+# ###############
+# PYRIGHT
+# ###############
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "basic"
+reportMissingParameterType = true
+ignore = ["tests/**"]

interloper_api-0.2.0/src/interloper_api/__init__.py

@@ -0,0 +1,3 @@
+from interloper_api.app import create_app
+
+__all__ = ["create_app"]

interloper_api-0.2.0/src/interloper_api/app.py

@@ -0,0 +1,100 @@
+"""FastAPI application factory for the interloper API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from interloper.catalog.base import Catalog
+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 (
+    assets,
+    auth,
+    backfills,
+    destinations,
+    external,
+    jobs,
+    oauth,
+    organisations,
+    resources,
+    runs,
+    sources,
+    ws,
+)
+from interloper_api.routes import catalog as catalog_routes
+
+
+def create_app(
+    store: Store | None = None,
+    catalog: Catalog | None = None,
+    auth_config: Any | None = None,
+    smtp_config: 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.
+        auth_config: ``AuthConfig`` instance for authentication settings.
+        smtp_config: ``SmtpConfig`` instance for sending invitation emails.
+        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=ws.realtime_lifespan, **kwargs)
+
+    if cors_origins:
+        app.add_middleware(
+            CORSMiddleware,  # type: ignore[arg-type]
+            allow_origins=cors_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    if store:
+        set_store(store)
+    if catalog:
+        set_catalog(catalog)
+    if auth_config:
+        set_auth_config(auth_config)
+    if smtp_config:
+        set_smtp_config(smtp_config)
+
+    api = APIRouter(prefix="/api")
+    api.include_router(auth.router, tags=["auth"])
+    api.include_router(organisations.router, tags=["organisations"])
+    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"])
+    api.include_router(destinations.router, prefix="/destinations", tags=["destinations"])
+    api.include_router(jobs.router, prefix="/jobs", tags=["jobs"])
+    api.include_router(runs.router, prefix="/runs", tags=["runs"])
+    api.include_router(backfills.router, prefix="/backfills", tags=["backfills"])
+    api.include_router(assets.router, prefix="/assets", tags=["assets"])
+    api.include_router(oauth.router, tags=["oauth"])
+    api.include_router(external.router, prefix="/external", tags=["external"])
+    api.include_router(ws.router, tags=["ws"])
+
+    try:
+        from interloper_api.routes import agent as agent_routes
+
+        api.include_router(agent_routes.router, prefix="/agent", tags=["agent"])
+    except ImportError:
+        pass
+
+    @api.get("/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok"}
+
+    app.include_router(api)
+
+    return app

interloper_api-0.2.0/src/interloper_api/dependencies.py

@@ -0,0 +1,293 @@
+"""Shared FastAPI dependencies for store, catalog, auth, and RBAC."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from fastapi import Cookie, Depends, HTTPException
+from interloper.catalog.base import Catalog
+from interloper_db import Organisation, Profile, Store
+from interloper_db.models import Session as SessionModel
+
+_store: Store | None = None
+_catalog: Catalog | None = None
+_auth_config: Any | None = None
+_smtp_config: Any | None = None
+
+# Role hierarchy: admin > editor > viewer
+_ROLE_RANK = {"viewer": 0, "editor": 1, "admin": 2}
+
+
+def set_store(store: Store) -> None:
+    """Set the global store instance.
+
+    Args:
+        store: The Store to use for all API operations.
+    """
+    global _store  # noqa: PLW0603
+    _store = store
+
+
+def set_catalog(catalog: Catalog) -> None:
+    """Set the global catalog instance.
+
+    Args:
+        catalog: The Catalog instance.
+    """
+    global _catalog  # noqa: PLW0603
+    _catalog = catalog
+
+
+def set_auth_config(auth_config: Any) -> None:
+    """Set the global auth config.
+
+    Args:
+        auth_config: The AuthConfig instance.
+    """
+    global _auth_config  # noqa: PLW0603
+    _auth_config = auth_config
+
+
+def get_store() -> Store:
+    """Return the global store instance.
+
+    Returns:
+        The Store.
+
+    Raises:
+        RuntimeError: If the store has not been set.
+    """
+    if _store is None:
+        raise RuntimeError("Store not initialized. Call set_store() first.")
+    return _store
+
+
+def get_catalog() -> dict[str, Any]:
+    """Return the global catalog as a serialized dict.
+
+    Returns:
+        Mapping from component key to serialized definition.
+
+    Raises:
+        RuntimeError: If the catalog has not been set.
+    """
+    if _catalog is None:
+        raise RuntimeError("Catalog not initialized. Call set_catalog() first.")
+    return _catalog.dump()
+
+
+def get_auth_config() -> Any:
+    """Return the global auth config.
+
+    Returns:
+        The AuthConfig instance.
+
+    Raises:
+        RuntimeError: If the auth config has not been set.
+    """
+    if _auth_config is None:
+        raise RuntimeError("Auth config not initialized. Call set_auth_config() first.")
+    return _auth_config
+
+
+def set_smtp_config(smtp_config: Any) -> None:
+    """Set the global SMTP config.
+
+    Args:
+        smtp_config: The SmtpConfig instance.
+    """
+    global _smtp_config  # noqa: PLW0603
+    _smtp_config = smtp_config
+
+
+def get_smtp_config() -> Any:
+    """Return the global SMTP config.
+
+    Returns:
+        The SmtpConfig instance, or None if not configured.
+    """
+    return _smtp_config
+
+
+# -- Auth dependencies -------------------------------------------------------
+
+
+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.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, SessionModel]:
+    """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.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.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")
+
+    org = store.get_organisation(session_row.organisation_id)
+    if not org:
+        raise HTTPException(status_code=404, detail="Organisation not found")
+
+    return org
+
+
+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  # type: ignore[return-value]
+
+
+# -- RBAC dependencies -------------------------------------------------------
+
+
+def _check_role(
+    minimum: str,
+    user: Profile,
+    org_id: UUID,
+    store: Store,
+) -> Profile:
+    """Verify the user has at least the required role in the org.
+
+    Args:
+        minimum: Minimum role required (``viewer``, ``editor``, ``admin``).
+        user: The authenticated user.
+        org_id: The active organisation UUID.
+        store: The Store instance.
+
+    Returns:
+        The authenticated Profile (pass-through for dependency chaining).
+
+    Raises:
+        HTTPException: 403 if insufficient permissions.
+    """
+    role = store.get_user_role(user.id, org_id)  # type: ignore[arg-type]
+    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]:
+        raise HTTPException(status_code=403, detail=f"Requires {minimum} role or higher")
+    return user
+
+
+def require_viewer(
+    user: Profile = Depends(get_current_user),
+    org_id: UUID = Depends(get_org_id),
+    store: Store = Depends(get_store),
+) -> Profile:
+    """Require at least ``viewer`` role. Any org member passes.
+
+    Returns:
+        The authenticated Profile.
+
+    Raises:
+        HTTPException: 401/403 on auth or role failure.
+    """
+    return _check_role("viewer", user, org_id, store)
+
+
+def require_editor(
+    user: Profile = Depends(get_current_user),
+    org_id: UUID = Depends(get_org_id),
+    store: Store = Depends(get_store),
+) -> Profile:
+    """Require at least ``editor`` role.
+
+    Returns:
+        The authenticated Profile.
+
+    Raises:
+        HTTPException: 401/403 on auth or role failure.
+    """
+    return _check_role("editor", user, org_id, store)
+
+
+def require_admin(
+    user: Profile = Depends(get_current_user),
+    org_id: UUID = Depends(get_org_id),
+    store: Store = Depends(get_store),
+) -> Profile:
+    """Require ``admin`` role.
+
+    Returns:
+        The authenticated Profile.
+
+    Raises:
+        HTTPException: 401/403 on auth or role failure.
+    """
+    return _check_role("admin", user, org_id, store)

interloper_api-0.2.0/src/interloper_api/email.py

@@ -0,0 +1,79 @@
+"""SMTP email utilities for sending invitation emails."""
+
+from __future__ import annotations
+
+import logging
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def send_invite_email(
+    smtp_config: Any,
+    to: str,
+    org_name: str,
+    inviter_name: str,
+    invite_url: str,
+) -> None:
+    """Send an organisation invitation email via SMTP.
+
+    Args:
+        smtp_config: SmtpConfig instance with host, port, user, password, from_addr.
+        to: Recipient email address.
+        org_name: Name of the organisation.
+        inviter_name: Display name of the person who sent the invite.
+        invite_url: Full URL to accept the invitation.
+
+    Raises:
+        RuntimeError: If SMTP is not configured.
+        smtplib.SMTPException: If sending fails.
+    """
+    if not smtp_config.enabled:
+        raise RuntimeError("SMTP is not configured. Set smtp.host, smtp.user, and smtp.password.")
+
+    msg = MIMEMultipart("alternative")
+    msg["Subject"] = f"You've been invited to join {org_name} on Interloper"
+    msg["From"] = smtp_config.from_addr
+    msg["To"] = to
+
+    text = (
+        f"{inviter_name} has invited you to join the {org_name} organisation on Interloper.\n\n"
+        f"Click the link below to accept the invitation:\n{invite_url}\n\n"
+        "This invitation expires in 7 days."
+    )
+
+    html = f"""\
+<html>
+<body style="font-family: sans-serif; color: #333;">
+    <h2>You've been invited to join {org_name}</h2>
+    <p>{inviter_name} has invited you to join the <strong>{org_name}</strong> organisation on Interloper.</p>
+    <p>
+        <a href="{invite_url}"
+           style="display: inline-block; padding: 10px 20px; background: #2563eb;
+                  color: #fff; text-decoration: none; border-radius: 6px;">
+            Accept Invitation
+        </a>
+    </p>
+    <p style="color: #666; font-size: 0.875rem;">This invitation expires in 7 days.</p>
+</body>
+</html>"""
+
+    msg.attach(MIMEText(text, "plain"))
+    msg.attach(MIMEText(html, "html"))
+
+    logger.info("Sending invite email to %s", to)
+
+    if smtp_config.port == 465:
+        with smtplib.SMTP_SSL(smtp_config.host, smtp_config.port) as server:
+            server.login(smtp_config.user, smtp_config.password)
+            server.sendmail(smtp_config.from_addr, to, msg.as_string())
+    else:
+        with smtplib.SMTP(smtp_config.host, smtp_config.port) as server:
+            server.starttls()
+            server.login(smtp_config.user, smtp_config.password)
+            server.sendmail(smtp_config.from_addr, to, msg.as_string())
+
+    logger.info("Invite email sent to %s", to)