fast-jelly! the Gel auth extension bindings for FastAPI

python-fastapi/examples/basic-async/README.md

@@ -1,7 +1,7 @@
 # Basic Async Example
 
 ```console
-$ uv run main.py
+$ uv run uvicorn app.main:fast_api
 ```
 
 ## Development

python-fastapi/examples/basic-async/app/auth.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+from typing import Annotated
+
+import json
+import logging
+import http
+
+import fastapi
+from fastapi import responses
+from gel.auth import email_password as core
+from gel_auth_fastapi import email_password as ext
+
+from . import dependencies as deps
+from .queries import create_user_async_edgeql as create_user_qry
+
+logger = logging.getLogger("fast_jelly")
+router = fastapi.APIRouter(tags=["Auth"])
+
+
+@router.post(
+    "/register",
+    response_class=responses.RedirectResponse,
+    status_code=http.HTTPStatus.SEE_OTHER,
+)
+async def register(
+    sign_up_body: Annotated[ext.SignUpBody, fastapi.Form()],
+    client: deps.CleanGelClient,
+    auth: deps.EmailPassword,
+    request: fastapi.Request,
+    response: fastapi.Response,
+):
+    sign_up_response = await auth.handle_sign_up(
+        sign_up_body,
+        verify_url=str(request.url_for("verify")),
+        response=response,
+    )
+    if not isinstance(sign_up_response, core.SignUpFailedResponse):
+        user = await create_user_qry.create_user(
+            client,
+            name=sign_up_body.email,
+            identity_id=sign_up_response.identity_id,
+        )
+        print(f"Created user: {json.dumps(user, default=str)}")
+
+    match sign_up_response:
+        case core.SignUpCompleteResponse():
+            return "/"
+        case core.SignUpVerificationRequiredResponse():
+            return "/signin?incomplete=verification_required"
+        case core.SignUpFailedResponse():
+            logger.error("sign up failed: %s", sign_up_response)
+            return "/signin?error=failure"
+        case _:
+            raise AssertionError("Invalid sign up response")
+
+
+@router.post(
+    "/authenticate",
+    response_class=responses.RedirectResponse,
+    status_code=http.HTTPStatus.SEE_OTHER,
+)
+async def authenticate(
+    sign_in_body: Annotated[ext.SignInBody, fastapi.Form()],
+    auth: deps.EmailPassword,
+    response: fastapi.Response,
+):
+    sign_in_response = await auth.handle_sign_in(
+        sign_in_body, response=response
+    )
+    match sign_in_response:
+        case core.SignInCompleteResponse():
+            return "/"
+        case core.SignInVerificationRequiredResponse():
+            return "/signin?incomplete=verification_required"
+        case core.SignInFailedResponse():
+            logger.error("sign in failed: %s", sign_in_response)
+            return "/signin?error=failure"
+        case _:
+            raise AssertionError("Invalid sign in response")
+
+
+@router.get(
+    "/verify",
+    response_class=responses.RedirectResponse,
+    status_code=http.HTTPStatus.SEE_OTHER,
+)
+async def verify(
+    verify_body: Annotated[ext.VerifyBody, fastapi.Query()],
+    auth: deps.EmailPassword,
+    verifier: deps.PKCEVerifier,
+):
+    verify_response = await auth.handle_verify_email(
+        verify_body, verifier=verifier
+    )
+
+    match verify_response:
+        case core.EmailVerificationCompleteResponse():
+            return "/"
+        case core.EmailVerificationMissingProofResponse():
+            return "/signin?incomplete=verify"
+        case core.EmailVerificationFailedResponse():
+            logger.error("verify email failed: %s", verify_response)
+            return "/signin?error=failure"
+        case _:
+            raise AssertionError("Invalid verify email response")
+
+
+@router.post(
+    "/send-password-reset",
+    response_class=responses.RedirectResponse,
+    status_code=http.HTTPStatus.SEE_OTHER,
+)
+async def send_password_reset(
+    send_password_reset_body: Annotated[
+        ext.SendPasswordResetBody, fastapi.Form()
+    ],
+    auth: deps.EmailPassword,
+    request: fastapi.Request,
+    response: fastapi.Response,
+):
+    send_password_reset_response = await auth.handle_send_password_reset(
+        send_password_reset_body,
+        reset_url=str(request.url_for("reset_password_page")),
+        response=response,
+    )
+    match send_password_reset_response:
+        case core.SendPasswordResetEmailCompleteResponse():
+            return "/signin?incomplete=password_reset_sent"
+        case core.SendPasswordResetEmailFailedResponse():
+            logger.error(
+                "send password reset failed: %s", send_password_reset_response
+            )
+            return "/signin?error=failure"
+        case _:
+            raise Exception("Invalid send password reset response")
+
+
+@router.post(
+    "/reset-password",
+    response_class=responses.RedirectResponse,
+    status_code=http.HTTPStatus.SEE_OTHER,
+)
+async def reset_password(
+    reset_password_body: Annotated[ext.PasswordResetBody, fastapi.Form()],
+    auth: deps.EmailPassword,
+    verifier: deps.PKCEVerifier,
+):
+    reset_password_response = await auth.handle_reset_password(
+        reset_password_body, verifier=verifier
+    )
+    match reset_password_response:
+        case core.PasswordResetCompleteResponse():
+            return "/"
+        case core.PasswordResetMissingProofResponse():
+            return "/signin?incomplete=reset_password"
+        case core.PasswordResetFailedResponse():
+            logger.error("reset password failed: %s", reset_password_response)
+            return "/signin?error=failure"
+        case _:
+            raise Exception("Invalid reset password response")

python-fastapi/examples/basic-async/app/configure_auth.py

@@ -0,0 +1,54 @@
+import asyncio
+import os
+import secrets
+
+from gel import create_async_client
+
+
+async def main():
+    client = create_async_client()
+
+    auth_signing_key = os.getenv(
+        "GEL_AUTH_SIGNING_KEY", secrets.token_urlsafe(32)
+    )
+
+    await client.execute(
+        f"""
+configure current branch reset ext::auth::AuthConfig;
+configure current branch reset ext::auth::ProviderConfig;
+configure current branch reset ext::auth::EmailPasswordProviderConfig;
+configure current branch reset cfg::EmailProviderConfig;
+
+configure current branch set
+ext::auth::AuthConfig::auth_signing_key := "{auth_signing_key}";
+
+configure current branch set
+ext::auth::AuthConfig::app_name := "Fast Jelly";
+
+configure current branch set
+ext::auth::AuthConfig::allowed_redirect_urls := {{"http://localhost:8000"}};
+
+configure current branch insert
+ext::auth::EmailPasswordProviderConfig {{
+    require_verification := true,
+}};
+
+configure current branch insert
+cfg::SMTPProviderConfig {{
+    name := "mailpit",
+    host := "localhost",
+    port := 1025,
+    username := "smtpuser",
+    password := "smtppassword",
+    sender := "[email protected]",
+    validate_certs := false,
+}};
+
+configure current branch set
+cfg::current_email_provider_name := "mailpit";
+        """
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python-fastapi/examples/basic-async/app/dependencies.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+from typing import Annotated
+
+import fastapi
+import gel
+from gel.auth import email_password as core
+from gel_auth_fastapi import email_password as ext, session
+
+
+AUTH_COOKIE_NAME = "fastjelly-auth"
+auth_token = session.AuthToken(AUTH_COOKIE_NAME)
+AuthToken = Annotated[str | None, fastapi.Depends(auth_token)]
+required_auth_token = session.AuthToken(AUTH_COOKIE_NAME, auto_error=True)
+RequiredAuthToken = Annotated[str, fastapi.Depends(auth_token)]
+
+VERIFIER_COOKIE_NAME = "fastjelly-verifier"
+pkce_verifier = session.PKCEVerifier(VERIFIER_COOKIE_NAME)
+PKCEVerifier = Annotated[str | None, fastapi.Depends(pkce_verifier)]
+
+
+def gel_client(request: fastapi.Request) -> gel.AsyncIOClient:
+    return request.app.state.client
+
+
+CleanGelClient = Annotated[gel.AsyncIOClient, fastapi.Depends(gel_client)]
+
+
+def gel_client_with_auth(
+    client: CleanGelClient, token: AuthToken
+) -> gel.AsyncIOClient:
+    return session.get_client_with_auth_token(client, auth_token=token)
+
+
+GelClient = Annotated[gel.AsyncIOClient, fastapi.Depends(gel_client_with_auth)]
+
+
+async def email_password(
+    request: fastapi.Request, client: CleanGelClient
+) -> ext.EmailPassword:
+    return ext.EmailPassword(
+        await core.make_async(client),
+        secure_cookie=request.base_url.is_secure,
+        verifier_cookie_name=VERIFIER_COOKIE_NAME,
+        auth_cookie_name=AUTH_COOKIE_NAME,
+    )
+
+
+EmailPassword = Annotated[ext.EmailPassword, fastapi.Depends(email_password)]

python-fastapi/examples/basic-async/app/events.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import datetime
+from http import HTTPStatus
+
+import gel
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from . import dependencies as deps
+from .queries import (
+    create_event_async_edgeql as create_event_qry,
+)
+
+router = APIRouter(tags=["API"])
+
+
+class RequestData(BaseModel):
+    name: str
+    address: str
+    schedule: datetime.datetime
+    host_name: str
+
+
+@router.post("/events", status_code=HTTPStatus.CREATED)
+async def post_event(
+    event: RequestData, client: deps.GelClient
+) -> create_event_qry.CreateEventResult:
+    try:
+        created_event = await create_event_qry.create_event(
+            client,
+            name=event.name,
+            address=event.address,
+            schedule=event.schedule,
+            host_name=event.host_name,
+        )
+    except gel.errors.InvalidValueError as ex:
+        raise HTTPException(
+            status_code=HTTPStatus.BAD_REQUEST,
+            detail={"error": str(ex)},
+        )
+
+    except gel.errors.ConstraintViolationError:
+        raise HTTPException(
+            status_code=HTTPStatus.BAD_REQUEST,
+            detail={"error": "Event '{event.name}' already exists"},
+        )
+
+    return created_event

python-fastapi/examples/basic-async/app/main.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import logging
+import sys
+
+import fastapi
+import gel
+
+from app import auth, users, events, ui
+
+
+formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")
+stream_handler = logging.StreamHandler(sys.stdout)
+stream_handler.setFormatter(formatter)
+
+logger = logging.getLogger("fast_jelly")
+logger.setLevel(logging.DEBUG)
+logger.addHandler(stream_handler)
+
+auth_core_logger = logging.getLogger("gel.auth")
+auth_core_logger.setLevel(logging.DEBUG)
+auth_core_logger.addHandler(stream_handler)
+
+
+async def startup():
+    fast_api.state.client = await gel.create_async_client().ensure_connected()
+
+
+async def shutdown():
+    await fast_api.state.client.aclose()
+
+
+fast_api = fastapi.FastAPI(
+    title="Jellyrole",
+    on_startup=[startup],
+    on_shutdown=[shutdown],
+)
+fast_api.include_router(ui.router)
+fast_api.include_router(auth.router, prefix="/auth")
+
+api_router = fastapi.APIRouter()
+api_router.include_router(users.router)
+api_router.include_router(events.router)
+
+fast_api.include_router(api_router, prefix="/api")

python-fastapi/examples/basic-async/app/queries/.gitattributes

@@ -0,0 +1 @@
+*.py    linguist-generated=true

python-fastapi/examples/basic-async/app/queries/create_event.edgeql

@@ -0,0 +1,16 @@
+with
+    name := <str>$name,
+    address := <str>$address,
+    schedule := <datetime>$schedule,
+    host_name := <str>$host_name,
+
+    HOST := (select default::User filter .name = host_name),
+    CREATED := (
+        insert default::Event {
+            name := name,
+            address := address,
+            schedule := schedule,
+            host := HOST,
+        }
+    ),
+select CREATED { *, host: { * } };