matrx-orm 3.1.217__tar.gz → 3.1.218__tar.gz

{matrx_orm-3.1.217 → matrx_orm-3.1.218}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.217
+Version: 3.1.218
 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

{matrx_orm-3.1.217 → matrx_orm-3.1.218}/matrx_orm/core/async_db_manager.py

@@ -19,6 +19,7 @@ from matrx_orm.core.config import (
     resolve_pool_mode,
 )
 from matrx_orm.error_handling import handle_orm_operation
+from matrx_orm.core.foreign_session_state import run_clearing_foreign_restrict
 from matrx_orm.core.pooler_role import (
     VERIFY_EMPTY_READS,
     assert_no_session_role_change,
@@ -1463,7 +1464,11 @@ class AsyncDatabaseManager:
                         in_transaction=False,
                     )
                     try:
-                        results = await conn.fetch(query, *args, timeout=driver_timeout)
+                        results = await run_clearing_foreign_restrict(
+                            conn,
+                            lambda: conn.fetch(query, *args, timeout=driver_timeout),
+                            what=f"execute_query {query[:80]!r}",
+                        )
                         if read_attempt > 0:
                             logger.warning(
                                 "[read-retry] SELECT HEALED on attempt %d after a "

{matrx_orm-3.1.217 → matrx_orm-3.1.218}/matrx_orm/core/db_function.py

@@ -69,6 +69,7 @@ from dataclasses import dataclass
 from typing import Any, Literal
 
 from matrx_orm.core.async_db_manager import AsyncDatabaseManager
+from matrx_orm.core.foreign_session_state import run_clearing_foreign_restrict
 from matrx_orm.core.statement_ceiling import DriverTimeout, resolve_driver_timeout
 from matrx_orm.core.transaction import get_active_connection
 from matrx_orm.core.write_retry import (
@@ -336,7 +337,11 @@ async def call_function(
 
     async def _attempt() -> Any:
         async with AsyncDatabaseManager.get_connection(database) as conn:
-            return await invoke(conn)
+            # Outside a transaction: a parse-time refusal caused by another pooler
+            # client's leaked restrict_nonsystem_relation_kind re-runs once, clearing it.
+            return await run_clearing_foreign_restrict(
+                conn, lambda: invoke(conn), what=f"call_function {schema}.{function}"
+            )
 
     # An RPC reaches Postgres on a RAW connection, bypassing execute_query
     # entirely, so it needs THE ONE loop explicitly — otherwise a deadlock inside
@@ -401,13 +406,20 @@ async def call_function_as(
                 operation=f"call_function_as {schema}.{function}",
                 in_transaction=False,
             )
-            if mode == "none":
-                await conn.execute(sql, *bound_args, timeout=driver_timeout)
-                return None
-            if mode == "rows":
-                rows = await conn.fetch(sql, *bound_args, timeout=driver_timeout)
-                return [dict(r) for r in rows]
-            return await conn.fetchval(sql, *bound_args, timeout=driver_timeout)
+
+            async def run() -> Any:
+                if mode == "none":
+                    await conn.execute(sql, *bound_args, timeout=driver_timeout)
+                    return None
+                if mode == "rows":
+                    rows = await conn.fetch(sql, *bound_args, timeout=driver_timeout)
+                    return [dict(r) for r in rows]
+                return await conn.fetchval(sql, *bound_args, timeout=driver_timeout)
+
+            # Same parse-time refusal class as call_function (foreign_session_state).
+            return await run_clearing_foreign_restrict(
+                conn, run, what=f"call_function_as {schema}.{function}"
+            )
 
     return await run_with_lock_retry(_attempt, config_name=database, query=sql, args=bound_args)
 

matrx_orm-3.1.218/matrx_orm/core/foreign_session_state.py

@@ -0,0 +1,112 @@
+"""Session state another client left on a shared server connection.
+
+WHY THIS EXISTS. We reach Postgres through Supavisor in TRANSACTION mode: every
+client shares the same pool of server connections, and Supavisor does not reset
+session state between clients. ``pg_dump`` (17.x) begins every run with a
+SESSION-level ``SET restrict_nonsystem_relation_kind = 'view, foreign-table'``.
+A dump pointed at the transaction pooler (port 6543) leaves that setting on
+whichever server connection the ``SET`` landed on, and every later statement of
+ours that touches a view through that connection is refused at parse time::
+
+    55000 ObjectNotInPrerequisiteStateError:
+        access to non-system view "organization_member" is restricted
+
+Measured 2026-10-05 05:49-09:04 UTC: ~50 platform errors (SEO runs list, mandate
+resolution, membership checks, file downloads), each pinned to a few poisoned
+backends that kept failing for minutes.
+
+THE DEFENCE (two halves, both here so they cannot drift apart):
+
+1. Every ORM transaction clears the setting transaction-locally at BEGIN
+   (:data:`CLEARED_GUCS`, merged into ``transaction._opening_statement_gucs``).
+   It rides the one opening statement, so it costs nothing.
+2. A statement OUTSIDE a transaction cannot carry a ``SET LOCAL`` in the same
+   round trip. When one is refused with exactly this parse-time error, it is
+   re-run ONCE inside a transaction that clears the setting first. The refusal
+   happens during parse/rewrite, before anything executes, so the re-run is
+   side-effect free. The cause is logged as a WARNING once per connection so it
+   never hides.
+"""
+
+from __future__ import annotations
+
+import logging
+import weakref
+from typing import Any, Awaitable, Callable, TypeVar
+
+logger = logging.getLogger(__name__)
+
+RESTRICT_GUC = "restrict_nonsystem_relation_kind"
+
+# Merged into every top-level transaction's opening GUCs. '' = no restriction
+# (the server default); set_config(..., true) scopes it to the transaction.
+CLEARED_GUCS: dict[str, str] = {RESTRICT_GUC: ""}
+
+_OBJECT_NOT_IN_PREREQUISITE_STATE = "55000"
+
+T = TypeVar("T")
+
+_warned: "weakref.WeakSet[Any]" = weakref.WeakSet()
+_warned_ids: set[int] = set()
+
+
+def is_foreign_restrict_refusal(exc: BaseException) -> bool:
+    """True iff ``exc`` is the parse-time refusal caused by a leaked restrict GUC."""
+    if getattr(exc, "sqlstate", None) != _OBJECT_NOT_IN_PREREQUISITE_STATE:
+        return False
+    text = str(exc)
+    return "access to non-system" in text and "is restricted" in text
+
+
+def _warn_once(conn: Any, exc: BaseException, what: str) -> None:
+    try:
+        if conn in _warned:
+            return
+        _warned.add(conn)
+    except TypeError:  # not weak-referenceable
+        if id(conn) in _warned_ids:
+            return
+        _warned_ids.add(id(conn))
+    logger.warning(
+        "[foreign-session-state] %s was refused because the shared server connection "
+        "carries %s from another client (a pg_dump through the transaction pooler sets it "
+        "session-wide and Supavisor does not reset it): %s — re-running once in a "
+        "transaction that clears it",
+        what,
+        RESTRICT_GUC,
+        exc,
+    )
+
+
+async def clear_in_transaction(conn: Any) -> None:
+    """Clear the restrict GUC for the current transaction on ``conn``."""
+    await conn.execute("SELECT set_config($1, '', true)", RESTRICT_GUC)
+
+
+async def run_clearing_foreign_restrict(
+    conn: Any, run: Callable[[], Awaitable[T]], *, what: str = "statement"
+) -> T:
+    """Run ``run()`` (one statement on ``conn``, outside any transaction).
+
+    On the leaked-restrict refusal, run it once more inside a transaction on the
+    same client connection that clears the setting first. Any other error, or a
+    second refusal, propagates unchanged.
+    """
+    try:
+        return await run()
+    except Exception as exc:
+        if not is_foreign_restrict_refusal(exc):
+            raise
+        _warn_once(conn, exc, what)
+    async with conn.transaction():
+        await clear_in_transaction(conn)
+        return await run()
+
+
+__all__ = [
+    "CLEARED_GUCS",
+    "RESTRICT_GUC",
+    "clear_in_transaction",
+    "is_foreign_restrict_refusal",
+    "run_clearing_foreign_restrict",
+]

{matrx_orm-3.1.217 → matrx_orm-3.1.218}/matrx_orm/core/transaction.py

@@ -460,9 +460,13 @@ def _opening_statement_gucs(opening_gucs: dict[str, str]) -> dict[str, str]:
     (a later name wins, exactly as sequential ``set_config`` calls did). ``role``
     is always LAST: everything before it is set while still the privileged role.
     """
+    from matrx_orm.core.foreign_session_state import CLEARED_GUCS
     from matrx_orm.core.session_context import session_context_gucs
 
-    merged = {**_TRANSACTION_CEILINGS, **session_context_gucs(), **opening_gucs}
+    # CLEARED_GUCS first: session state another pooler client may have left on this
+    # server connection (pg_dump's restrict_nonsystem_relation_kind) is cleared for
+    # every transaction; anything the opener declares still wins.
+    merged = {**CLEARED_GUCS, **_TRANSACTION_CEILINGS, **session_context_gucs(), **opening_gucs}
     if "role" in merged:
         merged["role"] = merged.pop("role")
     return merged

{matrx_orm-3.1.217 → matrx_orm-3.1.218}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.217"
+version = "3.1.218"
 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" }

{matrx_orm-3.1.217 → matrx_orm-3.1.218}/tests/level1/test_rls_session_scope.py

@@ -77,10 +77,11 @@ async def test_rls_session_commits_transaction_local_role(monkeypatch: pytest.Mo
     assert [sql for sql, _args in conn.calls] == [
         "BEGIN",
         "SELECT set_config($1, $2, true), set_config($3, $4, true), "
-        "set_config($5, $6, true), set_config($7, $8, true)",
+        "set_config($5, $6, true), set_config($7, $8, true), set_config($9, $10, true)",
         "COMMIT",
     ]
     assert conn.calls[1][1] == (
+        "restrict_nonsystem_relation_kind", "",
         "request.jwt.claims", '{"sub":"user-id","role":"authenticated"}',
         "statement_timeout", "30000",
         "idle_in_transaction_session_timeout", "30000",
@@ -116,10 +117,12 @@ async def test_lock_timeout_is_transaction_local_and_precedes_the_role(
     assert [sql for sql, _args in conn.calls] == [
         "BEGIN",
         "SELECT set_config($1, $2, true), set_config($3, $4, true), "
-        "set_config($5, $6, true), set_config($7, $8, true), set_config($9, $10, true)",
+        "set_config($5, $6, true), set_config($7, $8, true), set_config($9, $10, true), "
+        "set_config($11, $12, true)",
         "COMMIT",
     ]
     assert conn.calls[1][1] == (
+        "restrict_nonsystem_relation_kind", "",
         "request.jwt.claims", '{"role":"matrx_provisioner"}',
         "statement_timeout", "180000",
         "lock_timeout", "55000",
@@ -174,8 +177,9 @@ async def test_declared_context_and_rls_settings_share_one_round_trip_role_last(
     assert [sql for sql, _ in conn.calls][0::2] == ["BEGIN", "COMMIT"]
     assert len(conn.calls) == 3
     names = conn.calls[1][1][0::2]
-    assert names[0] == "lock_timeout"
-    assert names[1] == "app.actor_tier"
+    assert names[0] == "restrict_nonsystem_relation_kind"  # foreign session state cleared first
+    assert names[1] == "lock_timeout"
+    assert names[2] == "app.actor_tier"
     assert names.index("request.jwt.claims") < names.index("role")
     assert names[-1] == "role"
 

{matrx_orm-3.1.217 → matrx_orm-3.1.218}/tests/level1/test_transaction_gucs_one_round_trip.py

@@ -66,8 +66,9 @@ async def test_begin_sets_ceilings_and_declared_context_in_one_round_trip(monkey
     gucs = [call for call in conn.calls if "set_config" in call[0]]
     assert len(gucs) == 1, statements
     sql, args = gucs[0]
-    assert sql.count("set_config(") == 4
+    assert sql.count("set_config(") == 5
     assert args == (
+        "restrict_nonsystem_relation_kind", "",
         "lock_timeout", "5000",
         "app.actor_tier", "agent",
         "app.actor_system", "flashcards",
@@ -76,14 +77,17 @@ async def test_begin_sets_ceilings_and_declared_context_in_one_round_trip(monkey
 
 
 @pytest.mark.asyncio
-async def test_nothing_declared_emits_nothing(monkeypatch) -> None:
+async def test_nothing_declared_emits_only_the_foreign_state_clear(monkeypatch) -> None:
     conn = _Connection()
     monkeypatch.setattr(AdapterRegistry, "get", lambda _db: _Adapter(conn))
     monkeypatch.setattr(transaction_module, "_TRANSACTION_CEILINGS", {})
     configure_session_context(None)
     async with transaction_module.transaction("quiet"):
         pass
-    assert [sql for sql, _ in conn.calls] == ["BEGIN", "COMMIT"]
+    # The one GUC every transaction carries: another pooler client's leaked
+    # restrict_nonsystem_relation_kind is cleared (matrx_orm.core.foreign_session_state).
+    assert [sql for sql, _ in conn.calls] == ["BEGIN", "SELECT set_config($1, $2, true)", "COMMIT"]
+    assert conn.calls[1][1] == ("restrict_nonsystem_relation_kind", "")
 
 
 def test_a_bad_guc_name_is_refused_before_it_reaches_sql() -> None:

{matrx_orm-3.1.217 → matrx_orm-3.1.218}/tests/test_call_function_as.py

@@ -2,8 +2,8 @@
 
 The kernel's set form (``iam.accessible_entity_ids``) reads the person from
 ``auth.uid()``. The primitive must (1) never ride the caller's ambient transaction,
-(2) set the claims transaction-local BEFORE the call, inside one explicit
-transaction, and (3) refuse an empty person instead of returning the kernel's
+(2) set the claims transaction-local BEFORE the call, in the same single statement
+(its own transaction), and (3) refuse an empty person instead of returning the kernel's
 empty answer as if it were real.
 """
 
@@ -52,7 +52,14 @@ def log(monkeypatch):
     return calls
 
 
-async def test_claims_are_set_inside_one_transaction_before_the_call(log):
+async def test_claims_are_set_transaction_local_in_the_same_single_statement(log):
+    """ONE round trip: a MATERIALIZED CTE sets the claims, the call is correlated to it.
+
+    The single statement is its own transaction, so the claims end with it. No
+    BEGIN/COMMIT and no separate set_config trip (four trips before 2026-09-27). The
+    restrict_nonsystem_relation_kind clear (foreign_session_state) is NOT sent on a
+    healthy connection; it only rides a re-run after the parse-time refusal.
+    """
     out = await db_function.call_function_as(
         "11111111-1111-4111-8111-111111111111",
         "db",
@@ -62,21 +69,30 @@ async def test_claims_are_set_inside_one_transaction_before_the_call(log):
         db_function.TypedArg("viewer", "public.permission_level"),
     )
     assert out == ["a", "b"]
-    kinds = [c[0] for c in log]
-    assert kinds == ["acquire", "BEGIN", "execute", "fetchval", "COMMIT"]
-    set_claims = log[2]
-    assert "set_config('request.jwt.claims', $1, true)" in set_claims[1]
-    assert json.loads(set_claims[2][0]) == {
+    assert [c[0] for c in log] == ["acquire", "fetchval"]
+    _, sql, args = log[1]
+    assert sql == (
+        "WITH _claims AS MATERIALIZED (SELECT set_config('request.jwt.claims', $1, true) AS c) "
+        'SELECT (SELECT "iam"."accessible_entity_ids"($2, $3::"public"."permission_level") '
+        "WHERE _claims.c IS NOT NULL) FROM _claims"
+    )
+    assert json.loads(args[0]) == {
         "sub": "11111111-1111-4111-8111-111111111111",
         "role": "authenticated",
     }
-    assert log[3][1] == 'SELECT "iam"."accessible_entity_ids"($1, $2::"public"."permission_level")'
+    assert args[1:] == ("processed_document", "viewer")
+    assert "restrict_nonsystem_relation_kind" not in sql
 
 
 async def test_rows_mode_selects_from_the_function(log):
     rows = await db_function.call_function_as("u", "db", "platform", "search_items", "q", mode="rows")
     assert rows == [{"id": 1}]
-    assert log[3][1] == 'SELECT * FROM "platform"."search_items"($1)'
+    assert [c[0] for c in log] == ["acquire", "fetch"]
+    assert log[1][1] == (
+        "WITH _claims AS MATERIALIZED (SELECT set_config('request.jwt.claims', $1, true) AS c) "
+        'SELECT f.* FROM _claims, LATERAL (SELECT * FROM "platform"."search_items"($2) '
+        "WHERE _claims.c IS NOT NULL) f"
+    )
 
 
 async def test_an_empty_person_is_refused_not_answered_empty(log):

matrx_orm-3.1.218/tests/test_foreign_session_state.py

@@ -0,0 +1,110 @@
+"""A pooled server connection poisoned by another client's restrict GUC never fails our reads.
+
+pg_dump through the transaction pooler leaves ``restrict_nonsystem_relation_kind = 'view'``
+on a shared server connection; every view read through it is refused at parse time (55000).
+This fake connection behaves exactly like that backend: it refuses a view read unless the
+current transaction cleared the setting. Live proof: scripts/verify_foreign_restrict_guc_live.py.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from typing import Any
+
+import asyncpg
+import pytest
+
+from matrx_orm.core import foreign_session_state as fss
+from matrx_orm.core.transaction import _opening_statement_gucs
+
+
+def _refusal() -> Exception:
+    exc = asyncpg.exceptions.ObjectNotInPrerequisiteStateError(
+        'access to non-system view "organization_member" is restricted'
+    )
+    exc.sqlstate = "55000"
+    return exc
+
+
+class PoisonedConnection:
+    """Session carries restrict=view; a transaction may clear it locally."""
+
+    def __init__(self) -> None:
+        self.session_restrict = "view"
+        self.local_restrict: str | None = None
+        self.in_tx = False
+        self.executed: list[str] = []
+        self.view_reads = 0
+
+    @asynccontextmanager
+    async def transaction(self):
+        self.in_tx = True
+        try:
+            yield
+        finally:
+            self.in_tx = False
+            self.local_restrict = None
+
+    async def execute(self, sql: str, *args: Any) -> str:
+        self.executed.append(sql)
+        if "set_config" in sql and args and args[0] == fss.RESTRICT_GUC:
+            assert self.in_tx, "the clear must be transaction-local"
+            self.local_restrict = ""
+        return "SELECT 1"
+
+    async def fetchval(self, sql: str, *args: Any) -> Any:
+        effective = self.local_restrict if self.local_restrict is not None else self.session_restrict
+        if "view" in effective:
+            raise _refusal()
+        self.view_reads += 1
+        return 42
+
+
+def test_every_transaction_clears_the_restrict_guc_first() -> None:
+    gucs = _opening_statement_gucs({})
+    assert gucs[fss.RESTRICT_GUC] == ""
+    # An opener can still declare its own value, and role stays last.
+    assert _opening_statement_gucs({fss.RESTRICT_GUC: "view"})[fss.RESTRICT_GUC] == "view"
+    assert list(_opening_statement_gucs({"role": "authenticated"}))[-1] == "role"
+
+
+def test_statement_outside_a_transaction_heals_on_a_poisoned_connection(caplog) -> None:
+    conn = PoisonedConnection()
+    with caplog.at_level("WARNING"):
+        value = asyncio.run(
+            fss.run_clearing_foreign_restrict(conn, lambda: conn.fetchval("select v"), what="t")
+        )
+    assert value == 42
+    assert conn.view_reads == 1
+    assert conn.session_restrict == "view"  # session never touched — only the transaction
+    assert any(fss.RESTRICT_GUC in r.getMessage() for r in caplog.records)
+
+
+def test_warning_is_once_per_connection(caplog) -> None:
+    conn = PoisonedConnection()
+    with caplog.at_level("WARNING"):
+        for _ in range(3):
+            asyncio.run(fss.run_clearing_foreign_restrict(conn, lambda: conn.fetchval("x")))
+    assert sum(fss.RESTRICT_GUC in r.getMessage() for r in caplog.records) == 1
+
+
+def test_other_55000_errors_are_not_rerun() -> None:
+    conn = PoisonedConnection()
+    calls = 0
+
+    async def run() -> Any:
+        nonlocal calls
+        calls += 1
+        exc = asyncpg.exceptions.ObjectNotInPrerequisiteStateError("currval is not yet defined")
+        exc.sqlstate = "55000"
+        raise exc
+
+    with pytest.raises(asyncpg.exceptions.ObjectNotInPrerequisiteStateError):
+        asyncio.run(fss.run_clearing_foreign_restrict(conn, run))
+    assert calls == 1
+
+
+def test_classifier() -> None:
+    assert fss.is_foreign_restrict_refusal(_refusal())
+    assert not fss.is_foreign_restrict_refusal(RuntimeError("access to non-system view x is restricted"))