fix(django): make middleware truly hybrid-compatible with sync and async Django stacks

Addresses issues where PR #328 forced entire middleware chains into async mode,
breaking sync-only Django deployments.

Changes:
- Keep __call__ as sync method that conditionally routes to __acall__ for async paths
- Use markcoroutinefunction() to properly mark instances when async is detected
- Detect async/sync at init time via iscoroutinefunction(get_response)
- Restore process_exception method that was removed in #328 (fixes #329 regression)
- Add comprehensive test coverage for sync, async, and hybrid middleware behavior
- Add Django settings configuration to test suite

This implementation follows Django's recommended hybrid middleware pattern where
both sync_capable and async_capable are True, allowing Django to pass requests
without conversion while the middleware adapts based on the detected mode.

Fixes #329
Related to #328

Author: webjunkie

CHANGELOG.md

@@ -1,3 +1,8 @@
+# Unreleased
+
+- fix(django): Make middleware truly hybrid - compatible with both sync (WSGI) and async (ASGI) Django stacks without breaking sync-only deployments
+- fix(django): Restore exception capturing via `process_exception` method (regression from 6.7.5)
+
 # 6.7.9 - 2025-10-22
 
 - fix(flags): multi-condition flags with static cohorts returning wrong variants

posthog/integrations/django.py

@@ -3,13 +3,19 @@
 from posthog.client import Client
 
 try:
-    from asgiref.sync import iscoroutinefunction
+    from asgiref.sync import iscoroutinefunction, markcoroutinefunction
 except ImportError:
     # Fallback for older Django versions
     import asyncio
 
     iscoroutinefunction = asyncio.iscoroutinefunction
 
+    # Basic markcoroutinefunction implementation for older Django
+    def markcoroutinefunction(func):
+        func._is_coroutine = asyncio.coroutines._is_coroutine
+        return func
+
+
 if TYPE_CHECKING:
     from django.http import HttpRequest, HttpResponse  # noqa: F401
     from typing import Callable, Dict, Any, Optional, Union, Awaitable  # noqa: F401
@@ -39,26 +45,24 @@ class PosthogContextMiddleware:
     See the context documentation for more information. The extracted distinct ID and session ID, if found, are used to
     associate all events captured in the middleware context with the same distinct ID and session as currently active on the
     frontend. See the documentation for `set_context_session` and `identify_context` for more details.
+
+    This middleware is hybrid-capable: it supports both WSGI (sync) and ASGI (async) Django applications. The middleware
+    detects at initialization whether the next middleware in the chain is async or sync, and adapts its behavior accordingly.
+    This ensures compatibility with both pure sync and pure async middleware chains, as well as mixed chains in ASGI mode.
     """
 
-    # Django middleware capability flags
     sync_capable = True
     async_capable = True
 
     def __init__(self, get_response):
         # type: (Union[Callable[[HttpRequest], HttpResponse], Callable[[HttpRequest], Awaitable[HttpResponse]]]) -> None
+        self.get_response = get_response
         self._is_coroutine = iscoroutinefunction(get_response)
-        self._async_get_response = None  # type: Optional[Callable[[HttpRequest], Awaitable[HttpResponse]]]
-        self._sync_get_response = None  # type: Optional[Callable[[HttpRequest], HttpResponse]]
 
+        # Mark this instance as a coroutine function if get_response is async
+        # This is required for Django to correctly detect async middleware
         if self._is_coroutine:
-            self._async_get_response = cast(
-                "Callable[[HttpRequest], Awaitable[HttpResponse]]", get_response
-            )
-        else:
-            self._sync_get_response = cast(
-                "Callable[[HttpRequest], HttpResponse]", get_response
-            )
+            markcoroutinefunction(self)
 
         from django.conf import settings
 
@@ -181,40 +185,59 @@ def extract_request_user(self, request):
         return user_id, email
 
     def __call__(self, request):
-        # type: (HttpRequest) -> HttpResponse
-        # Purely defensive around django's internal sync/async handling - this should be unreachable, but if it's reached, we may
-        # as well return something semi-meaningful
+        # type: (HttpRequest) -> Union[HttpResponse, Awaitable[HttpResponse]]
+        """
+        Unified entry point for both sync and async request handling.
+
+        When sync_capable and async_capable are both True, Django passes requests
+        without conversion. This method detects the mode and routes accordingly.
+        """
         if self._is_coroutine:
-            raise RuntimeError(
-                "PosthogContextMiddleware received sync call but get_response is async"
-            )
+            return self.__acall__(request)
+        else:
+            # Synchronous path
+            if self.request_filter and not self.request_filter(request):
+                return self.get_response(request)
+
+            with contexts.new_context(self.capture_exceptions, client=self.client):
+                for k, v in self.extract_tags(request).items():
+                    contexts.tag(k, v)
 
+                return self.get_response(request)
+
+    async def __acall__(self, request):
+        # type: (HttpRequest) -> Awaitable[HttpResponse]
+        """
+        Asynchronous entry point for async request handling.
+
+        This method is called when the middleware chain is async.
+        """
         if self.request_filter and not self.request_filter(request):
-            assert self._sync_get_response is not None
-            return self._sync_get_response(request)
+            return await self.get_response(request)
 
         with contexts.new_context(self.capture_exceptions, client=self.client):
             for k, v in self.extract_tags(request).items():
                 contexts.tag(k, v)
 
-            assert self._sync_get_response is not None
-            return self._sync_get_response(request)
+            return await self.get_response(request)
 
-    async def __acall__(self, request):
-        # type: (HttpRequest) -> HttpResponse
+    def process_exception(self, request, exception):
+        """
+        Process exceptions raised during request handling.
+
+        This method is called by Django when an exception is raised during
+        request processing. It captures the exception and sends it to PostHog
+        if exception capturing is enabled.
+        """
         if self.request_filter and not self.request_filter(request):
-            if self._async_get_response is not None:
-                return await self._async_get_response(request)
-            else:
-                assert self._sync_get_response is not None
-                return self._sync_get_response(request)
+            return
 
-        with contexts.new_context(self.capture_exceptions, client=self.client):
-            for k, v in self.extract_tags(request).items():
-                contexts.tag(k, v)
+        if not self.capture_exceptions:
+            return
+
+        if self.client:
+            self.client.capture_exception(exception)
+        else:
+            from posthog import capture_exception
 
-            if self._async_get_response is not None:
-                return await self._async_get_response(request)
-            else:
-                assert self._sync_get_response is not None
-                return self._sync_get_response(request)
+            capture_exception(exception)