Enable asyncio debug mode in development, document async view safety

In DEBUG mode, enable loop.set_debug(True) with a 100ms slow callback
threshold. This surfaces blocking calls in async views (SSE, future
WebSocket handlers) without false positives — sync views run in the
thread pool and don't trigger the warning.

Update _finish_pipeline docstring to document thread affinity behavior
for async vs sync views. Add async view safety section to views README
and request_finished timing note to signals README.

Author: davegaeddert

plain/plain/internal/handlers/base.py

@@ -239,12 +239,19 @@ def _finish_pipeline(
     ) -> ResponseBase:
         """Run after-middleware and send request_finished signal.
 
-        request_finished is sent here (on the same thread as request_started)
-        rather than from response.close(), which runs after the response body
-        is written and may land on a different thread. This means the signal
-        fires before streaming responses are iterated — handlers like
-        close_old_connections should not affect in-progress streams since
-        request_started on the next request also handles stale connections.
+        For sync views, this runs on the same thread as request_started
+        (part of the single _run_sync_pipeline call).
+
+        For async views, this runs in a separate executor call and may
+        land on a different thread than request_started. Thread-local
+        state from request_started is not guaranteed to be available.
+        In practice this is safe because close_old_connections (the main
+        signal handler) is idempotent per-thread.
+
+        The signal fires before streaming response bodies are transmitted.
+        Handlers like close_old_connections should not affect in-progress
+        streams since request_started on the next request also handles
+        stale connections.
         """
         response = self._run_after_response(request, response, ran_before)
         signals.request_finished.send(sender=self.__class__)

plain/plain/server/workers/worker.py

@@ -144,6 +144,14 @@ def changed(fname: str) -> None:
     async def run(self) -> None:
         loop = asyncio.get_running_loop()
 
+        # Enable asyncio debug mode in development to detect blocking calls
+        # in async views. Logs a warning when a callback takes > 0.1s.
+        from plain.runtime import settings
+
+        if settings.DEBUG:
+            loop.set_debug(True)
+            loop.slow_callback_duration = 0.1
+
         # Signal handlers
         loop.add_signal_handler(signal.SIGTERM, self._signal_exit)
         loop.add_signal_handler(signal.SIGINT, self._signal_quit)

plain/plain/signals/README.md

@@ -32,7 +32,9 @@ request_finished.connect(on_request_finished)
 Plain provides two built-in signals:
 
 - `request_started` - sent when a request begins processing
-- `request_finished` - sent when a request finishes processing
+- `request_finished` - sent when a request finishes processing (after middleware completes, before the response body is transmitted)
+
+Note: for streaming responses (SSE, large downloads), `request_finished` fires while data is still being sent. Use `response.close()` or `_resource_closers` if you need a hook that runs after transmission completes.
 
 Your receiver function must accept `**kwargs` because signals may pass additional arguments in the future.
 

plain/plain/views/README.md

@@ -301,6 +301,24 @@ class AppRouter(Router):
 
 You can also redirect to a named URL using `url_name`, or preserve query parameters with `preserve_query_params=True`.
 
+## Async views
+
+Any view method defined with `async def` runs directly on the worker's event loop. This enables non-blocking I/O patterns like SSE, WebSockets, and async HTTP clients.
+
+**Important:** Blocking calls in async views freeze the entire worker process — no other requests can be processed until the blocking call returns. Plain's ORM, sessions, and auth layers are all synchronous and must not be called directly from async views.
+
+Common mistakes:
+
+- `User.query.get(pk=1)` — blocks the event loop
+- `time.sleep(1)` — use `await asyncio.sleep(1)` instead
+- `requests.get(...)` — use an async HTTP client instead
+
+To wrap a blocking call safely: `await asyncio.get_running_loop().run_in_executor(None, blocking_fn)`
+
+Use async views only for true async I/O (SSE, async HTTP clients). For standard request/response views that use the ORM, use regular sync views — they run in the thread pool and don't block other connections.
+
+In development (`DEBUG=True`), the server enables asyncio debug mode which logs warnings when a callback blocks the event loop for more than 100ms.
+
 ## ServerSentEventsView
 
 [`ServerSentEventsView`](./sse.py#ServerSentEventsView) provides [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) streaming. Subclass it and implement `stream()` as an async generator.