Rodin
64 lines
4.1 KiB
Markdown
64 lines
4.1 KiB
Markdown
# FastAPI Users source notes
|
|
|
|
Repo: `fastapi-users/fastapi-users`
|
|
Local checkout: `/home/ubuntu/repos/rodin-sources/fastapi-users`
|
|
|
|
## Why this repo was chosen
|
|
- This repo shows how a substantial FastAPI ecosystem package composes auth/user flows as routers plus dependency factories, rather than bespoke checks inside each endpoint.
|
|
- It is especially useful for identifying patterns around router composition, auth dependencies, and the behavior differences between strict and optional auth gates.
|
|
|
|
## Repeated patterns
|
|
|
|
### 1) Feature slices are delivered as routers and assembled centrally
|
|
- `examples/beanie-oauth/app/app.py:28-57` builds one `FastAPI(lifespan=...)` app and includes router factories for JWT auth, registration, password reset, verification, users, and OAuth.
|
|
- `tests/test_fastapi_users.py:24-42` repeats the same assembly pattern in tests, including multiple auth-related routers plus a users router.
|
|
|
|
Why chosen:
|
|
- The example app and the test app use the same composition model, which makes this a repeated package convention rather than demo-only structure.
|
|
|
|
Implication for synthesis:
|
|
- Strong evidence for composing auth/account features as routers, not implementing login/register/verify flows endpoint by endpoint.
|
|
|
|
### 2) Auth is expressed as dependency factories with explicit policy flags
|
|
- `examples/beanie-oauth/app/app.py:60-62` protects a route with `Depends(current_active_user)`.
|
|
- `tests/test_fastapi_users.py:44-114` shows the broader pattern: `fastapi_users.current_user(...)` generates dependencies for current, active, verified, superuser, and optional variants.
|
|
- `fastapi_users/router/oauth.py:235-237` derives `get_current_active_user` from `authenticator.current_user(active=True, verified=requires_verification)` and then injects it into the OAuth association route at `fastapi_users/router/oauth.py:257-262`.
|
|
|
|
Why chosen:
|
|
- This is stronger than a single protected-route example: policy is parameterized and reused as dependency wiring.
|
|
|
|
Implication for synthesis:
|
|
- Recommend expressing auth requirements in dependency declarations (`active=True`, `verified=True`, `superuser=True`, `optional=True`) rather than hidden role checks inside handlers.
|
|
|
|
### 3) Optional auth dependencies deliberately change failure behavior
|
|
- `tests/test_fastapi_users.py:156-203` shows non-optional `current_user` / `current_user(active=True)` endpoints returning `401` for missing or invalid tokens.
|
|
- `tests/test_fastapi_users.py:320-412` shows optional variants returning `200` with `null` when the token is missing, invalid, or does not satisfy the extra policy.
|
|
- `tests/test_fastapi_users.py:219-315` also distinguishes authorization outcomes: verified/superuser constraints return `403` when a valid user lacks the required property.
|
|
|
|
Why chosen:
|
|
- This is exactly the kind of subtle behavior shift that future synthesis could easily flatten incorrectly.
|
|
|
|
Caveat / counterexample:
|
|
- `optional=True` is not just "same dependency, but maybe absent." It changes endpoint semantics from auth failure to nullable user context.
|
|
|
|
Implication for synthesis:
|
|
- If optional auth appears in synthesized guidance, call out the semantic shift explicitly and avoid presenting it as a drop-in default.
|
|
|
|
### 4) Lifespan owns startup resources here too
|
|
- `examples/beanie-oauth/app/app.py:17-28` initializes Beanie in an `@asynccontextmanager` lifespan and passes it to `FastAPI(lifespan=...)`.
|
|
|
|
Why chosen:
|
|
- Confirms that ecosystem packages/examples align with the Starlette/FastAPI lifespan pattern rather than using import-time initialization.
|
|
|
|
## Strong citation candidates
|
|
- Router-factory composition in app assembly: `examples/beanie-oauth/app/app.py:28-57`
|
|
- Dependency-factory auth policies: `tests/test_fastapi_users.py:44-114`
|
|
- Optional auth returns `200` + `null` instead of `401/403`: `tests/test_fastapi_users.py:320-412`
|
|
- OAuth route derives auth dependency from policy flags: `fastapi_users/router/oauth.py:235-262`
|
|
|
|
## Pattern candidates supported by this repo
|
|
- compose auth/account feature areas as routers
|
|
- declare auth policy in dependencies rather than inline endpoint checks
|
|
- distinguish required auth from optional nullable-user contexts
|
|
- initialize backing resources in lifespan
|