Skip to content

docs(session): require a user in the quick start and take login credentials from the body - #343

Merged
allen0099 merged 1 commit into
masterfrom
docs/session-quickstart-321
Sep 28, 2026
Merged

allen0099 merged 1 commit into
masterfrom
docs/session-quickstart-321

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Problem

The session docs had two problems a first-time user copies straight into their app (#321):

  1. The Basic Usage /profile route used Depends(get_session) and then read session.user.user_id. get_session also accepts anonymous sessions (session.user is None), which exist as soon as any route writes to request.session, so such a visitor got a 500 (AttributeError) instead of a 401. The Full Example's profile, update and logout-all routes and the migration /me snippet had the same pattern.
  2. Every login example took username / password as query parameters, which puts passwords in URLs, browser history and access logs.

Change

  • docs/SESSION.md
    • Basic Usage: /profile uses AuthenticatedSession; login takes a LoginRequest pydantic body model. The follow-up paragraph now points at /profile instead of repeating a separate /account snippet, and notes that /logout only needs get_session.
    • Full Example: login takes LoginRequest; /api/user/profile, /api/user/update and /api/auth/logout-all use AuthenticatedSession. Routes that never read session.user (/api/messages, /api/auth/logout) keep get_session.
    • Migration section: the /me snippet uses require_user_session, which is added to the list of dependencies that work under either middleware.
    • Dependencies section: the SessionManagerDep login example takes LoginRequest instead of a username query parameter.
  • docs/JWT_CLAIMS.md: the complete application example's /auth/login takes a LoginRequest body model.
  • i18n/zh-TW/docs/SESSION.md, i18n/zh-TW/docs/JWT_CLAIMS.md: the same changes.

README.md, the other docs and examples/*.py were checked: examples/session_login.py and examples/session_jwt.py already take a pydantic body, and no other page has a query-parameter login or reads session.user through get_session. Docs only, so no changelog fragment.

Verification

  • Extracted the changed code blocks from both the English and zh-TW pages and ran them as FastAPI apps under fastapi.testclient against this branch's library (memory backend substituted for Redis; the JWT example without the custom multi-tenant serializer):
    • an anonymous session (started by a route writing request.session) gets 401 from /profile, /api/user/profile, /api/user/update, /api/auth/logout-all and /me; no session also gets 401;
    • login with a JSON body returns 200 and the token then reaches the protected routes (200); a wrong password returns 401; credentials in the query string are rejected with 422.
  • uv run pytest -q, uv run ruff check, uv run ruff format --check and uv run pre-commit run --all-files pass.

Closes #321

…ntials from the body

The Basic Usage /profile route read session.user through get_session, so a
visitor with an anonymous session (one started by any write to
request.session) got a 500 instead of a 401. /profile, the Full Example's
profile, update and logout-all routes, and the migration /me snippet now
use AuthenticatedSession / require_user_session.

Every login example in SESSION.md and JWT_CLAIMS.md took username and
password as query parameters, which puts passwords in URLs, browser history
and access logs. They now take a LoginRequest pydantic body model.

zh-TW translations updated to match.

Closes #321
@allen0099 allen0099 added this to the 0.3.9 milestone Sep 28, 2026
@allen0099 allen0099 added documentation Improvements or additions to documentation session Session management subsystem security Security vulnerability or hardening labels Sep 28, 2026
@allen0099
allen0099 merged commit 142d362 into master Sep 28, 2026
12 checks passed
@allen0099
allen0099 deleted the docs/session-quickstart-321 branch September 28, 2026 07:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation security Security vulnerability or hardening session Session management subsystem

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: the SESSION.md quick start returns 500 for anonymous sessions and takes the password in the query string

1 participant