matrx-orm 3.1.76__tar.gz → 3.1.77__tar.gz

{matrx_orm-3.1.76 → matrx_orm-3.1.77}/CLAUDE.md

@@ -39,7 +39,7 @@ Every table that becomes a Model needs row identity: a single-column primary key
   models do not quadratically populate the process identity cache. Contract:
   [`matrx_orm/query/FEATURE.md`](matrx_orm/query/FEATURE.md).
 - **Migrations**: `MigrationDB`, `MigrationLoader`, `MigrationExecutor`, `makemigrations`, `migrate` — migrations declare explicit `dependencies` and apply in topological order (no multi-head/merge support yet).
-- **Admin router** (FastAPI): `admin_router` exposes read/write endpoints for any registered model.
+- **Admin router** (FastAPI): `admin_router` exposes read/write endpoints for any registered model; bulk response rendering stays off the event loop. Contract: [`matrx_orm/admin/FEATURE.md`](matrx_orm/admin/FEATURE.md).
 - **API layer** (optional `[api]` extra): `APIServer`, `APIConfig`, `TokenAuth`.
 - **Adapters**: `AsyncPostgreSQLAdapter`, `SupabaseAdapter`, `PostgRESTClientAdapter`.
 - **Signals**: `pre_create`, `post_create`, `pre_save`, `post_save`, `pre_delete`, `post_delete`.

{matrx_orm-3.1.76 → matrx_orm-3.1.77}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.76
+Version: 3.1.77
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current
@@ -25,13 +25,14 @@ Requires-Python: >=3.13
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.17
+Requires-Dist: matrx-utils>=2.0.18
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: pyyaml>=6.0.3
 Provides-Extra: admin
 Requires-Dist: fastapi>=0.115; extra == 'admin'
+Requires-Dist: orjson>=3.10; extra == 'admin'
 Provides-Extra: api
 Requires-Dist: aiohttp>=3.9.0; extra == 'api'
 Description-Content-Type: text/markdown

matrx_orm-3.1.77/matrx_orm/admin/FEATURE.md

@@ -0,0 +1,23 @@
+# Admin router
+
+`router.py` exposes model-registry CRUD and cache operations through the optional
+FastAPI admin surface.
+
+## Response rendering
+
+- **Bulk row rendering never runs on the event loop.** `list_rows` passes row
+  serialization and JSON encoding through `_render_list_rows_response`, which
+  offloads the CPU-bound work with `asyncio.to_thread`; `orjson` bounds the
+  GIL-held encoding section.
+- **Keep both list aliases.** `data` and `rows` contain the same serialized rows;
+  admin clients use both shapes during compatibility transitions.
+- **The page cap is 2,000 rows.** Keep `ADMIN_LIST_MAX_PAGE_SIZE` aligned with the
+  dashboard constant in `orm-proxy.ts`.
+
+Verified against `router.py` and
+`tests/level1/test_admin_response_rendering.py` on 2026-08-17.
+
+## Change Log
+
+- 2026-08-17 — Moved bulk row serialization and JSON encoding off the event
+  loop after a 1.1-second production stall.

{matrx_orm-3.1.76 → matrx_orm-3.1.77}/matrx_orm/admin/router.py

@@ -24,6 +24,7 @@ Effective routes (relative to the mount prefix):
 
 from __future__ import annotations
 
+import asyncio
 import base64
 import binascii
 import json
@@ -32,7 +33,8 @@ import math
 import re
 from typing import Any
 
-from fastapi import APIRouter, HTTPException, Query, Request
+import orjson
+from fastapi import APIRouter, HTTPException, Query, Request, Response
 from fastapi.responses import JSONResponse
 
 from matrx_orm.core.expressions import Q
@@ -113,6 +115,46 @@ def _serialize(instance: Any) -> dict[str, Any]:
     return complete
 
 
+def _build_list_rows_response(
+    items: list[Any],
+    *,
+    total_count: int,
+    page: int,
+    page_size: int,
+) -> Response:
+    data = [_serialize(row) for row in items]
+    total_pages = math.ceil(total_count / page_size) if page_size > 0 else 0
+    return Response(
+        content=orjson.dumps(
+            {
+                "data": data,
+                "rows": data,
+                "total": total_count,
+                "page": page,
+                "page_size": page_size,
+                "total_pages": total_pages,
+            }
+        ),
+        media_type="application/json",
+    )
+
+
+async def _render_list_rows_response(
+    items: list[Any],
+    *,
+    total_count: int,
+    page: int,
+    page_size: int,
+) -> Response:
+    return await asyncio.to_thread(
+        _build_list_rows_response,
+        items,
+        total_count=total_count,
+        page=page,
+        page_size=page_size,
+    )
+
+
 def _decode_row_id(model: type, row_id: str) -> str | dict[str, Any]:
     primary_keys = list(model._meta.primary_keys or ())
     if len(primary_keys) <= 1:
@@ -605,7 +647,7 @@ async def list_rows(
     sort_dir: str = Query("asc", pattern="^(asc|desc)$"),
     search: str | None = Query(None, description="Column filters as 'col1:val1,col2:val2'"),
     schema: str | None = Query(None, description="PostgreSQL schema name"),
-) -> JSONResponse:
+) -> Response:
     model = _require_model(table_name, schema)
     log.info(
         "list_rows: table=%s page=%d size=%d sort_by=%s sort_dir=%s search=%s",
@@ -629,25 +671,18 @@ async def list_rows(
         paginator = Paginator(qb, per_page=page_size)
         # page() is 1-based; our API uses 0-based pages
         page_obj = await paginator.page(page + 1)
-        data = [_serialize(row) for row in page_obj.items]
-        total_pages = math.ceil(page_obj.total_count / page_size) if page_size > 0 else 0
-
         log.info(
             "list_rows: %s returned %d rows (total %d)",
             table_name,
-            len(data),
+            len(page_obj.items),
             page_obj.total_count,
         )
 
-        return JSONResponse(
-            content={
-                "data": data,
-                "rows": data,
-                "total": page_obj.total_count,
-                "page": page,
-                "page_size": page_size,
-                "total_pages": total_pages,
-            }
+        return await _render_list_rows_response(
+            page_obj.items,
+            total_count=page_obj.total_count,
+            page=page,
+            page_size=page_size,
         )
 
     except ValueError:

{matrx_orm-3.1.76 → matrx_orm-3.1.77}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.76"
+version = "3.1.77"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }
@@ -41,7 +41,7 @@ dependencies = [
     "gitpython>=3.1.40",
     "psycopg[binary]>=3.2.5",
     "psycopg-pool>=3.2.5",
-    "matrx-utils>=2.0.17",
+    "matrx-utils>=2.0.18",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",
@@ -59,6 +59,7 @@ api = [
 ]
 admin = [
     "fastapi>=0.115",
+    "orjson>=3.10",
 ]
 
 [project.scripts]

matrx_orm-3.1.77/tests/level1/test_admin_response_rendering.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import asyncio
+import importlib
+import json
+import time
+
+import pytest
+
+admin_router = importlib.import_module("matrx_orm.admin.router")
+
+
+class _Row:
+    def __init__(self, row_id: int) -> None:
+        self.row_id = row_id
+
+
+def test_build_list_rows_response_preserves_admin_envelope(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(admin_router, "_serialize", lambda row: {"id": row.row_id})
+
+    response = admin_router._build_list_rows_response(
+        [_Row(1), _Row(2)],
+        total_count=5,
+        page=1,
+        page_size=2,
+    )
+
+    payload = json.loads(response.body)
+    assert payload == {
+        "data": [{"id": 1}, {"id": 2}],
+        "rows": [{"id": 1}, {"id": 2}],
+        "total": 5,
+        "page": 1,
+        "page_size": 2,
+        "total_pages": 3,
+    }
+
+
+@pytest.mark.asyncio
+async def test_render_list_rows_response_keeps_event_loop_responsive(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def slow_serialize(row: _Row) -> dict[str, int]:
+        time.sleep(0.05)
+        return {"id": row.row_id}
+
+    monkeypatch.setattr(admin_router, "_serialize", slow_serialize)
+    render_task = asyncio.create_task(
+        admin_router._render_list_rows_response(
+            [_Row(1)],
+            total_count=1,
+            page=0,
+            page_size=25,
+        )
+    )
+
+    await asyncio.sleep(0.01)
+
+    assert not render_task.done()
+    response = await render_task
+    assert json.loads(response.body)["data"] == [{"id": 1}]