Sync & Async Adapters

## The requirement A **hybrid** Django middleware runs without any adapter whether the project is served by a WSGI server (sync requests) or an ASGI server (async requests). Two things make it hybrid: 1. **Declare it**: the factory must have `sync_capable = True` and `async_capable = True`. On a function factory, `django.utils.decorators.sync_and_async_middleware` sets both. 2. **Match the mode**: Django passes the factory a `get_response`. If that is a coroutine function, the returned callable must be a coroutine function too; otherwise it must be a plain function. The factory decides **once**, at startup, with `inspect.iscoroutinefunction(get_response)`. The declaration alone is not enough. The `sync_and_async_middleware` decorator only sets two attributes; Django then trusts the middleware and does not wrap it, so a single-path body would be wrong in one of the two modes. ## A function-based tenant resolver Tenant resolution is a good fit: every request needs `request.tenant`, and resolving it is I/O (a database or cache lookup) that should not block the event loop in async mode. ```python from inspect import iscoroutinefunction from django.http import HttpResponseNotFound from django.utils.decorators import sync_and_async_middleware from tenants.models import Tenant def subdomain_of(request): return request.get_host().split(":")[0].split(".")[0] @sync_and_async_middleware def tenant_middleware(get_response): if iscoroutinefunction(get_response): async def middleware(request): qs = Tenant.objects.filter(subdomain=subdomain_of(request)) tenant = await qs.afirst() if tenant is None: return HttpResponseNotFound("Unknown tenant") request.tenant = tenant return await get_response(request) else: def middleware(request): qs = Tenant.objects.filter(subdomain=subdomain_of(request)) tenant = qs.first() if tenant is None: return HttpResponseNotFound("Unknown tenant") request.tenant = tenant return get_response(request) return middleware ``` Points to notice: - The branch runs **once**, when Django builds the stack, not per request. - Each branch uses only calls of its own kind: `await qs.afirst()` in the async one, `qs.first()` in the sync one. Calling the sync ORM from the async branch raises `SynchronousOnlyOperation`. - Short-circuiting (returning a 404 without calling `get_response`) works the same way in both branches. ## The class-based form and the coroutine marker A class is often more convenient when the middleware has helpers or configuration. The catch is that an **instance** with an `async def __call__` is not recognised as a coroutine function by `inspect.iscoroutinefunction()`. Django wraps every middleware instance in an exception-to-response converter that inspects its target this way, and a hybrid middleware above yours inspects its own `get_response` the same way. An unmarked async instance therefore looks synchronous: the layer above takes its sync path and receives an un-awaited coroutine instead of a response. The fix is `inspect.markcoroutinefunction(self)`, the same pattern Django's `MiddlewareMixin` uses: ```python from inspect import iscoroutinefunction, markcoroutinefunction class TenantMiddleware: sync_capable = True async_capable = True def __init__(self, get_response): self.get_response = get_response self.async_mode = iscoroutinefunction(get_response) if self.async_mode: markcoroutinefunction(self) def __call__(self, request): if self.async_mode: return self.__acall__(request) request.tenant = resolve_tenant(request) return self.get_response(request) async def __acall__(self, request): request.tenant = await aresolve_tenant(request) return await self.get_response(request) ``` `__call__` stays a plain `def` (so the sync path works) and returns the coroutine from `__acall__` in async mode, which the caller awaits. ## What you get, and what you do not | Deployment | What Django does with the hybrid middleware | |---|---| | WSGI | Calls the sync branch directly; no adapter | | ASGI, all other middleware async-capable | Calls the async branch directly; no thread is held while the view runs | | ASGI, a sync-only middleware sits between you and the view | Django may call you in **sync** mode, because it minimises switches | That last row surprises people: the docs note that a hybrid middleware may be called in a mode that does not match the view, because Django optimises the whole chain for the fewest sync/async transitions. Also be honest about the lookup itself. Removing the middleware adapter does not make every call inside non-blocking; Django's async ORM methods such as `afirst()` still run the query through its sync-to-async bridge. What the hybrid design removes is the **adapter around the middleware**, which otherwise keeps a thread for the whole downstream call. ## Checklist - Both flags `True`, via the decorator or class attributes. - One `iscoroutinefunction(get_response)` decision at construction time. - Async branch: `async def`, `await get_response(request)`, async-safe I/O only. - Class form: `markcoroutinefunction(self)` in async mode. - Verify with `DEBUG = True` and debug logging for `django.request`: no "handler adapted" line should name your middleware.