perf: skip Python Response wrapping for bare dict/list/str/bytes returns (#1384)

* perf: skip Python Response wrapping for bare dict/list/str/bytes returns

Handlers that return a dict/list/str/bytes no longer allocate a Python-side
`Response(...)` or fresh `Headers({...})` per request. The router now lets
those values flow through to the Rust executor, which:

- downcasts `#[pyclass] Response` directly (0 getattr calls) when the user
  did return one,
- serializes bare dicts/lists via a cached `orjson.dumps`,
- wraps bare str/bytes with prebuilt content-type headers,
- falls back to the existing `FromPyObject<Response>` chain for subclasses.

Also skips the per-request `contextvars.Context()` allocation when no
middleware is registered — the #1380 cross-phase context is only needed
when `before_request`/`after_request` hooks can mutate `ContextVar`s.

Local micro-benchmark on `/json` (workers=1, processes=1, single-threaded
urllib client): 4013 rps -> 5728 rps (+43%).

All 339 integration tests and 23 unit tests pass (6 pre-existing
`test_openapi_schema.py` failures unrelated to this change).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: address CodeRabbit feedback

- cargo fmt: wrap the `get_description_from_pyobject` call that rustfmt
  flagged on the PyResponse fast path.
- `downcast_exact::<PyResponse>()` so user Response subclasses with
  overridden properties fall through to the getattr slow path, preserving
  their custom read semantics.
- `downcast` (not `downcast_exact`) for PyDict/PyList/PyString/PyBytes so
  primitive subclasses match the Python router's `isinstance(...)` gate
  instead of falling through to the FromPyObject chain (which would fail
  with TypeError).
- Revert the conditional per-request `contextvars.Context()`: with it
  skipped, sync handlers calling `ContextVar.set(...)` would leak values
  into the next request on the same worker thread, weakening the #1380
  isolation guarantee. The J1-J4 fast paths alone still deliver the win
  (~+43% locally on /json with workers=1, processes=1).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sansyrox

robyn/router.py

@@ -25,6 +25,16 @@
 _logger = logging.getLogger(__name__)
 
 
+# Prebuilt Headers singletons reused across every request so the hot path
+# doesn't allocate a fresh DashMap per response. These objects are passed
+# into `Response(...)` as-is; the Rust side clones them into an independent
+# `Headers` struct during extraction, so server-side header injection never
+# mutates the singleton. Handlers that return a bare dict/list/str/bytes
+# never receive the Response and can't mutate it either.
+_JSON_HEADERS = Headers({"Content-Type": "application/json"})
+_TEXT_HEADERS = Headers({"Content-Type": "text/plain"})
+
+
 def lower_http_method(method: HttpMethod):
     return (str(method))[11:].lower()
 
@@ -80,7 +90,7 @@ def _format_tuple_response(self, res: tuple) -> Response:
     def _format_response(
         self,
         res: Union[Dict, List, Response, StreamingResponse, bytes, tuple, str],
-    ) -> Union[Response, StreamingResponse]:
+    ) -> Union[Response, StreamingResponse, dict, list, str, bytes]:
         if isinstance(res, Response):
             return res
 
@@ -91,16 +101,15 @@ def _format_response(
         if pydantic_json is not None:
             return Response(
                 status_code=status_codes.HTTP_200_OK,
-                headers=Headers({"Content-Type": "application/json"}),
+                headers=_JSON_HEADERS,
                 description=pydantic_json,
             )
 
-        if isinstance(res, (dict, list)):
-            return Response(
-                status_code=status_codes.HTTP_200_OK,
-                headers=Headers({"Content-Type": "application/json"}),
-                description=jsonify(res),
-            )
+        # Bare dict/list/str/bytes are handled natively in the Rust executor:
+        # it serializes dicts/lists via orjson and wraps str/bytes directly,
+        # skipping the per-request Python-side Response/Headers construction.
+        if isinstance(res, (dict, list, str, bytes)):
+            return res
 
         if isinstance(res, FileResponse):
             response: Response = Response(
@@ -111,19 +120,12 @@ def _format_response(
             response.file_path = res.file_path
             return response
 
-        if isinstance(res, bytes):
-            return Response(
-                status_code=status_codes.HTTP_200_OK,
-                headers=Headers({"Content-Type": "application/octet-stream"}),
-                description=res,
-            )
-
         if isinstance(res, tuple):
             return self._format_tuple_response(tuple(res))
 
         return Response(
             status_code=status_codes.HTTP_200_OK,
-            headers=Headers({"Content-Type": "text/plain"}),
+            headers=_TEXT_HEADERS,
             description=str(res).encode("utf-8"),
         )
 
@@ -206,7 +208,7 @@ def wrapped_handler(*args, **kwargs):
                             except ValueError as e:
                                 return Response(
                                     status_code=status_codes.HTTP_400_BAD_REQUEST,
-                                    headers=Headers({"Content-Type": "application/json"}),
+                                    headers=_JSON_HEADERS,
                                     description=jsonify({"error": f"Invalid JSON body: {e}"}),
                                 )
                         elif issubclass(handler_param_type, Body):
@@ -219,7 +221,7 @@ def wrapped_handler(*args, **kwargs):
                             except ValueError as e:
                                 return Response(
                                     status_code=status_codes.HTTP_400_BAD_REQUEST,
-                                    headers=Headers({"Content-Type": "application/json"}),
+                                    headers=_JSON_HEADERS,
                                     description=jsonify({"error": f"Invalid JSON body: {e}"}),
                                 )
 
@@ -280,13 +282,13 @@ async def async_inner_handler(*args, **kwargs):
             except QueryParamValidationError as err:
                 response = Response(
                     status_code=status_codes.HTTP_400_BAD_REQUEST,
-                    headers=Headers({"Content-Type": "text/plain"}),
+                    headers=_TEXT_HEADERS,
                     description=str(err),
                 )
             except PydanticBodyValidationError as err:
                 response = Response(
                     status_code=status_codes.HTTP_422_UNPROCESSABLE_ENTITY,
-                    headers=Headers({"Content-Type": "application/json"}),
+                    headers=_JSON_HEADERS,
                     description=jsonify(err.error_detail),
                 )
             except Exception as err:
@@ -306,13 +308,13 @@ def inner_handler(*args, **kwargs):
             except QueryParamValidationError as err:
                 response = Response(
                     status_code=status_codes.HTTP_400_BAD_REQUEST,
-                    headers=Headers({"Content-Type": "text/plain"}),
+                    headers=_TEXT_HEADERS,
                     description=str(err),
                 )
             except PydanticBodyValidationError as err:
                 response = Response(
                     status_code=status_codes.HTTP_422_UNPROCESSABLE_ENTITY,
-                    headers=Headers({"Content-Type": "application/json"}),
+                    headers=_JSON_HEADERS,
                     description=jsonify(err.error_detail),
                 )
             except Exception as err:

src/executors/mod.rs

@@ -5,17 +5,153 @@ use std::sync::Arc;
 
 use anyhow::Result;
 use pyo3::prelude::*;
+use pyo3::sync::PyOnceLock;
+use pyo3::types::{PyBytes, PyDict, PyList, PyString};
 use pyo3::{BoundObject, IntoPyObject};
 use pyo3_async_runtimes::TaskLocals;
 
 use crate::asyncio::run_in_context_helper;
+use crate::types::cookie::Cookies;
+use crate::types::headers::Headers;
+use crate::types::response::PyResponse;
 use crate::types::{
     function_info::FunctionInfo,
     request::Request,
     response::{Response, ResponseType, StreamingResponse},
     MiddlewareReturn,
 };
 
+/// Cached `orjson.dumps` callable. Resolved once at first use, reused across
+/// every request that returns a bare `dict`/`list` from its handler.
+static ORJSON_DUMPS: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
+
+fn orjson_dumps<'py>(py: Python<'py>) -> PyResult<&'py Bound<'py, PyAny>> {
+    Ok(ORJSON_DUMPS
+        .get_or_try_init(py, || -> PyResult<Py<PyAny>> {
+            Ok(py.import("orjson")?.getattr("dumps")?.unbind())
+        })?
+        .bind(py))
+}
+
+#[inline]
+fn json_headers() -> Headers {
+    let h = Headers::default();
+    h.headers
+        .entry("content-type".to_string())
+        .or_default()
+        .push("application/json".to_string());
+    h
+}
+
+#[inline]
+fn text_plain_headers() -> Headers {
+    let h = Headers::default();
+    h.headers
+        .entry("content-type".to_string())
+        .or_default()
+        .push("text/plain".to_string());
+    h
+}
+
+#[inline]
+fn octet_stream_headers() -> Headers {
+    let h = Headers::default();
+    h.headers
+        .entry("content-type".to_string())
+        .or_default()
+        .push("application/octet-stream".to_string());
+    h
+}
+
+#[inline]
+fn response_from_bytes(body: Vec<u8>, headers: Headers) -> Response {
+    Response {
+        status_code: 200,
+        response_type: "text".to_string(),
+        headers,
+        description: body,
+        file_path: None,
+        cookies: Cookies::default(),
+    }
+}
+
+/// Try every fast path before falling back to the generic `FromPyObject for
+/// Response` conversion. Order matters:
+///   1. `#[pyclass] Response`  — read fields from the Rust struct directly.
+///   2. `dict`/`list`          — hand to orjson, skip Python-side wrapping.
+///   3. `str`/`bytes`          — wrap in a preset Response.
+///   4. `StreamingResponse`    — existing extract path.
+///   5. Fallback               — `FromPyObject` chain (handles subclasses).
+#[inline]
+fn extract_response_type_fast(output: &Bound<'_, PyAny>) -> PyResult<ResponseType> {
+    let py = output.py();
+
+    // 1. PyResponse pyclass downcast — zero getattr calls.
+    //    `downcast_exact` (not `downcast`) so that user `Response` subclasses
+    //    with overridden properties fall through to the getattr-based slow
+    //    path below, preserving their custom read semantics.
+    if let Ok(py_resp) = output.downcast_exact::<PyResponse>() {
+        let borrowed = py_resp.borrow();
+        let description =
+            crate::types::get_description_from_pyobject(borrowed.description.bind(py))?;
+        let headers = borrowed.headers.borrow(py).clone();
+        let cookies = borrowed.cookies.borrow(py).clone();
+        return Ok(ResponseType::Standard(Response {
+            status_code: borrowed.status_code,
+            response_type: borrowed.response_type.clone(),
+            headers,
+            description,
+            file_path: borrowed.file_path.clone(),
+            cookies,
+        }));
+    }
+
+    // 2. Bare dict/list — serialize via orjson directly in Rust.
+    //    Uses subclass-aware `downcast` to match the Python router's
+    //    `isinstance(res, (dict, list, ...))` check; orjson serializes
+    //    dict/list subclasses as their base type by default.
+    if output.downcast::<PyDict>().is_ok() || output.downcast::<PyList>().is_ok() {
+        let dumps = orjson_dumps(py)?;
+        let encoded = dumps.call1((output,))?;
+        let bytes = encoded.downcast::<PyBytes>()?.as_bytes().to_vec();
+        return Ok(ResponseType::Standard(response_from_bytes(
+            bytes,
+            json_headers(),
+        )));
+    }
+
+    // 3. Bare str/bytes — `downcast` (subclass-aware) to match the Python
+    //    router's `isinstance` gate.
+    if let Ok(s) = output.downcast::<PyString>() {
+        let bytes = s.to_string().into_bytes();
+        return Ok(ResponseType::Standard(response_from_bytes(
+            bytes,
+            text_plain_headers(),
+        )));
+    }
+    if let Ok(b) = output.downcast::<PyBytes>() {
+        let bytes = b.as_bytes().to_vec();
+        return Ok(ResponseType::Standard(response_from_bytes(
+            bytes,
+            octet_stream_headers(),
+        )));
+    }
+
+    // 4. StreamingResponse (duck-typed via `content`/`media_type` attrs).
+    if let Ok(streaming) = output.extract::<StreamingResponse>() {
+        return Ok(ResponseType::Streaming(streaming));
+    }
+
+    // 5. Slow-path fallback: anything that implements the Response protocol
+    //    (e.g. user subclasses) still works through the getattr chain.
+    match output.extract::<Response>() {
+        Ok(response) => Ok(ResponseType::Standard(response)),
+        Err(_) => Err(PyErr::new::<pyo3::exceptions::PyTypeError, _>(
+            "Function must return a Response, StreamingResponse, dict, list, str, or bytes",
+        )),
+    }
+}
+
 #[inline]
 fn get_function_output<'a, T>(
     function: &'a FunctionInfo,
@@ -410,29 +546,12 @@ pub async fn execute_http_function(
 
 #[inline]
 fn extract_response_type(output: Py<PyAny>, py: Python) -> PyResult<ResponseType> {
-    // Try Response first (most common case), then StreamingResponse
-    match output.extract::<Response>(py) {
-        Ok(response) => Ok(ResponseType::Standard(response)),
-        Err(_) => match output.extract::<StreamingResponse>(py) {
-            Ok(streaming_response) => Ok(ResponseType::Streaming(streaming_response)),
-            Err(_) => Err(PyErr::new::<pyo3::exceptions::PyTypeError, _>(
-                "Function must return a Response or StreamingResponse",
-            )),
-        },
-    }
+    extract_response_type_fast(output.bind(py))
 }
 
 #[inline]
 fn extract_response_type_bound(output: pyo3::Bound<'_, pyo3::PyAny>) -> PyResult<ResponseType> {
-    match output.extract::<Response>() {
-        Ok(response) => Ok(ResponseType::Standard(response)),
-        Err(_) => match output.extract::<StreamingResponse>() {
-            Ok(streaming_response) => Ok(ResponseType::Streaming(streaming_response)),
-            Err(_) => Err(PyErr::new::<pyo3::exceptions::PyTypeError, _>(
-                "Function must return a Response or StreamingResponse",
-            )),
-        },
-    }
+    extract_response_type_fast(&output)
 }
 
 pub async fn execute_startup_handler(

src/server.rs

@@ -507,6 +507,11 @@ async fn index(
     // handler and to `after_request` hooks. asyncio copies the current context
     // for each task it creates, so without this shared object each phase would
     // see its own isolated snapshot (see issue #1380).
+    //
+    // This also provides per-request ContextVar isolation for sync handlers
+    // (which run via `ctx.run(...)`): without a fresh context, a `ContextVar`
+    // written inside a handler would persist in the worker thread's current
+    // context and leak into the next request on that thread.
     let request_context: Py<PyAny> = match Python::with_gil(crate::asyncio::new_context) {
         Ok(ctx) => ctx,
         Err(e) => {