Skip to content

docs: clarify BaseHTTPMiddleware impact on contextvars for subsequent middleware - #2943

Merged
Kludex merged 4 commits into
Kludex:masterfrom
yakimka:contextvars-middlewre-docs
Sep 6, 2025
Merged

docs: clarify BaseHTTPMiddleware impact on contextvars for subsequent middleware#2943
Kludex merged 4 commits into
Kludex:masterfrom
yakimka:contextvars-middlewre-docs

Conversation

@yakimka

@yakimka yakimka commented May 24, 2025

Copy link
Copy Markdown
Contributor

This PR updates the documentation for BaseHTTPMiddleware to clarify an important limitation regarding contextvars propagation.

The "Limitations" section previously noted that BaseHTTPMiddleware prevents contextvars changes from propagating upwards. This change adds a crucial detail: if a BaseHTTPMiddleware is positioned earlier in the middleware stack, it will also disrupt contextvars propagation for any subsequent Pure ASGI Middleware that relies on them.

This clarification helps users understand a potential pitfall when mixing BaseHTTPMiddleware and Pure ASGI Middleware, ensuring they design their middleware stack appropriately for contextvars to function as expected.

Example

from __future__ import annotations

import contextvars
import random
from typing import TYPE_CHECKING

import uvicorn
from fastapi import Request, Response
from starlette.applications import Starlette
from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
from starlette.responses import JSONResponse
from starlette.routing import Route

if TYPE_CHECKING:
    from starlette.types import ASGIApp, Receive, Scope, Send


context = contextvars.ContextVar("context", default=None)


class BadMiddleware(BaseHTTPMiddleware):
    async def dispatch(
        self, request: Request, call_next: RequestResponseEndpoint
    ) -> Response:
        print("BadMiddleware called")
        response = await call_next(request)
        print("BadMiddleware context:", context.get())
        print("BadMiddleware finished")
        return response


class ShinyMiddleware:
    def __init__(self, app: ASGIApp) -> None:
        self.app = app

    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return

        print("ShinyMiddleware called")
        await self.app(scope, receive, send)
        print("ShinyMiddleware context:", context.get())
        print("ShinyMiddleware finished")


async def homepage(request):
    random_int = random.randint(1, 100)
    context.set({"random_int": random_int})
    return JSONResponse({"random_int": random_int})


app = Starlette(debug=True, routes=[
    Route("/", homepage),
])


app.add_middleware(ShinyMiddleware)
app.add_middleware(BadMiddleware)


if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

If you run this app and curl localhost:8000, you can see that everything happens as described in the documentation:

BadMiddleware called
ShinyMiddleware called
BadMiddleware context: None
BadMiddleware finished
INFO:     127.0.0.1:55240 - "GET / HTTP/1.1" 200 OK
ShinyMiddleware context: {'random_int': 97}
ShinyMiddleware finished

But if you swap BadMiddleware and ShinyMiddleware, you will get unexpected (?) behavior:

ShinyMiddleware called
BadMiddleware called
BadMiddleware context: None
BadMiddleware finished
INFO:     127.0.0.1:55332 - "GET / HTTP/1.1" 200 OK
ShinyMiddleware context: None
ShinyMiddleware finished

Checklist

  • I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
  • I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
  • I've updated the documentation accordingly.

@yakimka yakimka changed the title [DOCS] Clarify BaseHTTPMiddleware impact on contextvars for subsequent middleware docs: clarify BaseHTTPMiddleware impact on contextvars for subsequent middleware May 24, 2025
@Kludex
Kludex enabled auto-merge (squash) September 6, 2025 10:41
@Kludex

Kludex commented Sep 6, 2025

Copy link
Copy Markdown
Owner

Thanks!

@Kludex
Kludex merged commit 73d83e9 into Kludex:master Sep 6, 2025
7 checks passed
exa160 added a commit to exa160/yande.re-spider that referenced this pull request Jun 10, 2026
@exa160
fix(middleware): Pure ASGI + DAO session refetch to fix POST not comm…
33a2616 
…itting

## Root cause (two bugs, not one)

### Bug 1: BaseHTTPMiddleware cross-task ContextVar
BaseHTTPMiddleware.dispatch() uses anyio.create_task_group() to run
endpoints in a new asyncio task. ContextVars do NOT propagate across
asyncio task boundaries (Python language guarantee). Symptom:
endpoint's _request_session.get() returned None (cross-task default).

### Bug 2 (the real culprit): BaseDAO.session caches the first session
Even after fixing Bug 1, POSTs would commit only the FIRST request's
data and silently fail on subsequent requests. The cause: favorite_dao
is a module-level singleton. First call to .session property stored
the result in self._session permanently. Next request:
  - dispatch creates new session B, sets ContextVar to B
  - favorite_dao.session returns cached A (now closed)
  - INSERT into closed A: silently lost
This is also why v1.1.1's 'with FavoriteDao() as dao:' pattern worked
for scheduler tasks (DAO created fresh each call) but NOT for HTTP
endpoints (singletons used directly).

## Fixes

1. middleware/session.py: Pure ASGI middleware (not BaseHTTPMiddleware)
   - Direct await self.app(scope, receive, send): no task spawn
   - ContextVar propagates correctly within same task
   - get_session() in strict mode: RuntimeError instead of silent
     fallback (catches future ContextVar regressions immediately)
   - API-compatible: init_app / get_session / remove_session unchanged
   - src/__init__.py and DAO callers untouched

2. dao/database.py: BaseDAO.session refetches ContextVar per call
   - Single-instance path: always read fresh from ContextVar
   - No more stale closed session across requests
   - Explicit construction (with FavoriteDao(s) as dao:) preserved

## Verified
- 6 consecutive POSTs all land in DB (count 8 -> 14, fix3-1..6)
- 8 endpoints e2e (4x 200 OK, 4x pre-existing 404/405 unrelated)
- 0 zombie transactions after restart + 6 POSTs
- Lifespan starts cleanly (Loaded 0 scheduled folders from DB)
- get_session() strict mode: no false positive in lifespan (uses with)

## Series
- v1.1.1: zombie stale read (BaseDAO.owns_session + with scheduler)
- v1.1.2: JSON storage (native MariaDB JSON column)
- v1.1.3: zombie write (Pure ASGI + DAO refetch) -- root cause

Refs: https://starlette.dev/middleware/ (BaseHTTPMiddleware limitations)
Refs: Kludex/starlette#1678
Refs: Kludex/starlette#2943
Refs: Kludex/starlette#2160
@exa160 exa160 mentioned this pull request Jun 11, 2026
Closed
@coderabbitai coderabbitai Bot mentioned this pull request Jul 31, 2026
Merged
@coderabbitai coderabbitai Bot mentioned this pull request Aug 19, 2026
Merged
6 tasks
exa160 added a commit to exa160/yande.re-spider that referenced this pull request Aug 24, 2026
@exa160
fix(middleware): Pure ASGI + DAO session refetch to fix POST not comm…
6082a11 
…itting

## Root cause (two bugs, not one)

### Bug 1: BaseHTTPMiddleware cross-task ContextVar
BaseHTTPMiddleware.dispatch() uses anyio.create_task_group() to run
endpoints in a new asyncio task. ContextVars do NOT propagate across
asyncio task boundaries (Python language guarantee). Symptom:
endpoint's _request_session.get() returned None (cross-task default).

### Bug 2 (the real culprit): BaseDAO.session caches the first session
Even after fixing Bug 1, POSTs would commit only the FIRST request's
data and silently fail on subsequent requests. The cause: favorite_dao
is a module-level singleton. First call to .session property stored
the result in self._session permanently. Next request:
  - dispatch creates new session B, sets ContextVar to B
  - favorite_dao.session returns cached A (now closed)
  - INSERT into closed A: silently lost
This is also why v1.1.1's 'with FavoriteDao() as dao:' pattern worked
for scheduler tasks (DAO created fresh each call) but NOT for HTTP
endpoints (singletons used directly).

## Fixes

1. middleware/session.py: Pure ASGI middleware (not BaseHTTPMiddleware)
   - Direct await self.app(scope, receive, send): no task spawn
   - ContextVar propagates correctly within same task
   - get_session() in strict mode: RuntimeError instead of silent
     fallback (catches future ContextVar regressions immediately)
   - API-compatible: init_app / get_session / remove_session unchanged
   - src/__init__.py and DAO callers untouched

2. dao/database.py: BaseDAO.session refetches ContextVar per call
   - Single-instance path: always read fresh from ContextVar
   - No more stale closed session across requests
   - Explicit construction (with FavoriteDao(s) as dao:) preserved

## Verified
- 6 consecutive POSTs all land in DB (count 8 -> 14, fix3-1..6)
- 8 endpoints e2e (4x 200 OK, 4x pre-existing 404/405 unrelated)
- 0 zombie transactions after restart + 6 POSTs
- Lifespan starts cleanly (Loaded 0 scheduled folders from DB)
- get_session() strict mode: no false positive in lifespan (uses with)

## Series
- v1.1.1: zombie stale read (BaseDAO.owns_session + with scheduler)
- v1.1.2: JSON storage (native MariaDB JSON column)
- v1.1.3: zombie write (Pure ASGI + DAO refetch) -- root cause

Refs: https://starlette.dev/middleware/ (BaseHTTPMiddleware limitations)
Refs: Kludex/starlette#1678
Refs: Kludex/starlette#2943
Refs: Kludex/starlette#2160
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Kludex Kludex Kludex approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@yakimka @Kludex