You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tooling.apache.org by ar...@apache.org on 2026/10/21 14:13:42 UTC

(tooling-trusted-releases) branch 299 created (now 6e03dae6)

This is an automated email from the ASF dual-hosted git repository.

alitheg pushed a change to branch 299
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git


      at 6e03dae6 #299 - Documentation of session detachment and good practice

This branch includes the following new commits:

     new b34edc19 #299 - Throw informative errors on use of detached objects or modified with a session closed without commit. Add static checking for nested sessions or models passed as arguments.
     new 6e03dae6 #299 - Documentation of session detachment and good practice

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org


(tooling-trusted-releases) 01/02: #299 - Throw informative errors on use of detached objects or modified with a session closed without commit. Add static checking for nested sessions or models passed as arguments.

Posted by ar...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

alitheg pushed a commit to branch 299
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git

commit b34edc19860061b54ee5556019a28102e60e4b80
Author: Alastair McFarlane <ar...@apache.org>
AuthorDate: Tue Oct 20 12:24:26 2026 +0100

    #299 - Throw informative errors on use of detached objects or modified with a session closed without commit. Add static checking for nested sessions or models passed as arguments.
---
 .pre-commit-config.yaml                   |   8 ++
 atr/admin/__init__.py                     |   6 +-
 atr/db/__init__.py                        |  69 ++++++++++
 atr/db/interaction.py                     |   8 +-
 atr/get/committees.py                     |   2 +-
 atr/get/root.py                           |   2 +-
 atr/get/test.py                           |   3 +-
 atr/post/projects.py                      |  60 ++++-----
 atr/post/vote.py                          |   4 +-
 atr/post/voting.py                        |   2 -
 atr/sessions.py                           |  14 +-
 atr/storage/writers/vote.py               |  25 ++--
 scripts/lint/check_session_boundaries.py  | 205 ++++++++++++++++++++++++++++++
 tests/unit/test_session_guards.py         | 171 +++++++++++++++++++++++++
 tests/unit/test_sessions.py               |  14 +-
 tests/unit/test_svn_publish_start_vote.py |   2 +-
 tests/unit/test_vote_serials.py           |   5 +-
 17 files changed, 528 insertions(+), 72 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 09750291..a3a9d6d6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -185,6 +185,14 @@ repos:
       pass_filenames: false
       always_run: true
 
+    - id: check-session-boundaries
+      name: check session boundaries
+      description: Check that db.session() is not nested inside storage contexts and that writers take keys, not ORM objects
+      entry: uv run --frozen python scripts/lint/check_session_boundaries.py
+      language: system
+      pass_filenames: false
+      always_run: true
+
     - id: check-when-dependencies-updated
       name: check when dependencies were updated
       description: Verify that dependencies were updated within the configured timeframe, for ASVS 15.1.1
diff --git a/atr/admin/__init__.py b/atr/admin/__init__.py
index 2bcbf091..dcdd7495 100644
--- a/atr/admin/__init__.py
+++ b/atr/admin/__init__.py
@@ -1862,9 +1862,9 @@ async def toggle_view_post(
 
     Toggle between admin and user views.
     """
-    session.session.downgrade_admin_to_user = not session.session.downgrade_admin_to_user
-    await asfquart.APP.sessions.save(session.session, {"downgrade_admin_to_user"})
-    quart.g.is_session_downgraded = session.session.downgrade_admin_to_user
+    downgraded = not session.session.downgrade_admin_to_user
+    await asfquart.APP.sessions.save(session.session, {"downgrade_admin_to_user": downgraded})
+    quart.g.is_session_downgraded = downgraded
 
     message = "Viewing as regular user" if session.session.downgrade_admin_to_user else "Viewing as admin"
     await quart.flash(message, "success")
diff --git a/atr/db/__init__.py b/atr/db/__init__.py
index abdcb2b9..98430105 100644
--- a/atr/db/__init__.py
+++ b/atr/db/__init__.py
@@ -29,6 +29,7 @@ import sqlalchemy.dialects.sqlite
 import sqlalchemy.event as event
 import sqlalchemy.ext.asyncio
 import sqlalchemy.orm as orm
+import sqlalchemy.orm.attributes as attributes
 import sqlalchemy.sql
 import sqlmodel
 import sqlmodel.sql.expression as expression
@@ -51,6 +52,7 @@ if TYPE_CHECKING:
 global_log_query: bool = False
 _global_atr_engine: sqlalchemy.ext.asyncio.AsyncEngine | None = None
 _global_atr_sessionmaker: sqlalchemy.ext.asyncio.async_sessionmaker | None = None
+_global_detached_guard_installed: bool = False
 
 
 T = TypeVar("T")
@@ -84,6 +86,14 @@ NOT_SET: Final[NotSet] = NotSet()
 type Opt[T] = T | NotSet
 
 
+class DetachedMutationError(RuntimeError):
+    pass
+
+
+class UnflushedChangesError(RuntimeError):
+    pass
+
+
 class Query[T]:
     def __init__(self, session: Session, query: expression.SelectOfScalar[T]):
         self.query = query
@@ -163,6 +173,16 @@ class Session(sqlalchemy.ext.asyncio.AsyncSession):
         if explicit_value_passed_by_sessionmaker is not None:
             self.log_queries = explicit_value_passed_by_sessionmaker
 
+    # This is __aexit__ and not close() because the async close runs in a shielded task
+    # which cannot see an exception that is propagating out of the block
+    async def __aexit__(self, type_: Any, value: Any, traceback: Any) -> None:
+        sync = self.sync_session
+        pending = [o for o in sync.dirty if sync.is_modified(o)] + list(sync.new) + list(sync.deleted)
+        await super().__aexit__(type_, value, traceback)
+        if pending and (type_ is None):
+            names = ", ".join(sorted({type(o).__name__ for o in pending}))
+            raise UnflushedChangesError(f"Session closed with uncommitted changes to: {names}")
+
     # TODO: Need to type all of these arguments correctly
 
     async def begin_immediate(self) -> None:
@@ -1337,6 +1357,7 @@ def init_database(app: base.QuartApp) -> None:
         _global_atr_sessionmaker = sqlalchemy.ext.asyncio.async_sessionmaker(
             bind=engine, class_=Session, expire_on_commit=False
         )
+        install_detached_mutation_guard()
 
         # Run any pending migrations on startup
         log.info("Applying database migrations via init_database...")
@@ -1380,6 +1401,22 @@ async def init_database_for_worker() -> None:
     _global_atr_sessionmaker = sqlalchemy.ext.asyncio.async_sessionmaker(
         bind=engine, class_=Session, expire_on_commit=False
     )
+    install_detached_mutation_guard()
+
+
+def install_detached_mutation_guard() -> None:
+    global _global_detached_guard_installed
+    if _global_detached_guard_installed:
+        return
+    for mapper in sqlmodel.SQLModel._sa_registry.mappers:
+        for prop in mapper.attrs:
+            instrumented = getattr(mapper.class_, prop.key)
+            if instrumented.impl.collection:
+                event.listen(instrumented, "append", _collection_guard(prop.key))
+                event.listen(instrumented, "remove", _collection_guard(prop.key))
+            else:
+                event.listen(instrumented, "set", _scalar_guard(prop.key))
+    _global_detached_guard_installed = True
 
 
 def is_defined[T](v: T | NotSet) -> TypeGuard[T]:
@@ -1495,9 +1532,41 @@ def session_function[**P, R](
     return wrapper
 
 
+def set_committed_value(instance: object, key: str, value: object) -> None:
+    """Populate an attribute as if loaded, without marking the instance dirty or firing events."""
+    attributes.set_committed_value(instance, key, value)
+
+
 async def shutdown_database() -> None:
     if _global_atr_engine:
         log.info("Closing database")
         await _global_atr_engine.dispose()
     else:
         log.info("No database to close")
+
+
+def _check_detached(target: object, attr_key: str, initiator: attributes.AttributeEventToken) -> None:
+    if not attributes.instance_state(target).detached:
+        return
+    # Setting a back-populated relationship fires the other side first, so we name
+    # the attribute the caller wrote, which the initiator records
+    origin = f"{initiator.impl.class_.__name__}.{initiator.impl.key}"
+    touched = f"{type(target).__name__}.{attr_key}"
+    where = origin if (origin == touched) else f"{origin} (via {touched})"
+    raise DetachedMutationError(
+        f"{where} was set on a detached instance - its session has closed, so this write would be silently discarded"
+    )
+
+
+def _collection_guard(attr_key: str) -> Callable[[object, object, attributes.AttributeEventToken], None]:
+    def guard(target: object, value: object, initiator: attributes.AttributeEventToken) -> None:
+        _check_detached(target, attr_key, initiator)
+
+    return guard
+
+
+def _scalar_guard(attr_key: str) -> Callable[[object, object, object, attributes.AttributeEventToken], None]:
+    def guard(target: object, value: object, old_value: object, initiator: attributes.AttributeEventToken) -> None:
+        _check_detached(target, attr_key, initiator)
+
+    return guard
diff --git a/atr/db/interaction.py b/atr/db/interaction.py
index 68b8c347..21f6dbb3 100644
--- a/atr/db/interaction.py
+++ b/atr/db/interaction.py
@@ -145,7 +145,7 @@ async def all_releases(project: sql.Project) -> list[sql.Release]:
             results.append(release)
 
     for release in results:
-        release.project = project
+        db.set_committed_value(release, "project", project)
 
     try:
         # This rejects any non PEP 440 versions
@@ -945,8 +945,8 @@ async def releases_by_phase(project: sql.Project, phase: sql.ReleasePhase) -> li
             results.append(release)
 
     for release in results:
-        # Don't need to eager load and lose it when the session closes
-        release.project = project
+        # The caller already has the project, so stitch it on as loaded state rather than eager loading
+        db.set_committed_value(release, "project", project)
     return results
 
 
@@ -1193,7 +1193,7 @@ async def user_topnav(
     for project in user_projects:
         active_releases = releases_by_project.get(project.key, [])
         for release in active_releases:
-            release.project = project
+            db.set_committed_value(release, "project", project)
         if not user.can_view_embargoed_release(project.committee, asf_uid, is_member=is_member):
             active_releases = [r for r in active_releases if (not r.is_embargoed)]
         if active_releases:
diff --git a/atr/get/committees.py b/atr/get/committees.py
index dc3c141e..1c8a5c7d 100644
--- a/atr/get/committees.py
+++ b/atr/get/committees.py
@@ -102,7 +102,7 @@ async def view(session: web.Committer, _committees: Literal["committees"], name:
 
     project_list = list(committee.projects)
     for project in project_list:
-        project.committee = committee
+        db.set_committed_value(project, "committee", committee)
     project_list.sort(key=lambda p: interaction.project_order_key(p, latest_releases.get(str(p.key))))
     signing_keys = sorted(
         committee.signing_certificates,
diff --git a/atr/get/root.py b/atr/get/root.py
index 30598df8..40ad9e09 100644
--- a/atr/get/root.py
+++ b/atr/get/root.py
@@ -117,7 +117,7 @@ async def index(_session: web.Public, _root: Literal[""]) -> quart_response.Resp
         for project in user_projects:
             active_releases = releases_by_project.get(project.key, [])
             for release in active_releases:
-                release.project = project
+                db.set_committed_value(release, "project", project)
             if not user.can_view_embargoed_release(project.committee, uid, is_member=session_data.is_member):
                 active_releases = [r for r in active_releases if (not r.is_embargoed)]
             all_projects.append(
diff --git a/atr/get/test.py b/atr/get/test.py
index 95ccd7f5..1967b3a5 100644
--- a/atr/get/test.py
+++ b/atr/get/test.py
@@ -236,8 +236,7 @@ async def test_recheck_session(
     if not isinstance(existing, sql.UserSession):
         raise base.ASFQuartException("No session to recheck", errorcode=400)
 
-    existing.last_account_check = 0
-    await asfquart.APP.sessions.save(existing, {"last_account_check"})
+    await asfquart.APP.sessions.save(existing, {"last_account_check": 0})
     return await web.redirect(root.index)
 
 
diff --git a/atr/post/projects.py b/atr/post/projects.py
index f51f6b7f..5c4391aa 100644
--- a/atr/post/projects.py
+++ b/atr/post/projects.py
@@ -600,42 +600,42 @@ async def _request_approval(
             get.projects.projects, error="CAP approval is not configured. Please contact an administrator."
         )
 
+    async with db.session() as data:
+        project = await data.project(key=str(project_key), _committee=True, _releases=True).get()
+        if (project is None) or (project.committee is None):
+            return await session.redirect(get.projects.projects, error=f"Project '{project_key}' not found.")
+        if project.committee.is_podling:
+            return await session.redirect(
+                get.projects.projects,
+                error=(
+                    "CAP approval voting is not available for podlings. Archival or deletion of a podling is an"
+                    " Incubator PMC decision."
+                ),
+            )
+        committee_key = project.committee.key
+        display_name = project.display_name
+        active_siblings = len(
+            await data.project(committee_key=committee_key, status=sql.ProjectStatus.ACTIVE, _committee=False).all()
+        )
+        eligibility_error = _action_eligibility_error(project, action, active_siblings)
+        if eligibility_error is not None:
+            return await session.redirect(get.projects.projects, error=eligibility_error)
+        existing = await data.approval_request(
+            project_key=str(project_key),
+            status_in=[sql.ApprovalStatus.PENDING, sql.ApprovalStatus.APPROVED],
+        ).get()
+        if existing is not None:
+            return await session.redirect(
+                get.projects.projects,
+                error=f"A CAP approval request to {existing.action.value} this project is already in progress.",
+            )
+
     async with storage.write(session) as write:
         try:
             wacm = await _write_as_committee_member(write, session, project_key)
         except storage.AccessError as e:
             return await session.redirect(get.projects.projects, error=f"Error requesting {action.value} approval: {e}")
 
-        async with db.session() as data:
-            project = await data.project(key=str(project_key), _committee=True, _releases=True).get()
-            if (project is None) or (project.committee is None):
-                return await session.redirect(get.projects.projects, error=f"Project '{project_key}' not found.")
-            if project.committee.is_podling:
-                return await session.redirect(
-                    get.projects.projects,
-                    error=(
-                        "CAP approval voting is not available for podlings. Archival or deletion of a podling is an"
-                        " Incubator PMC decision."
-                    ),
-                )
-            committee_key = project.committee.key
-            display_name = project.display_name
-            active_siblings = len(
-                await data.project(committee_key=committee_key, status=sql.ProjectStatus.ACTIVE, _committee=False).all()
-            )
-            eligibility_error = _action_eligibility_error(project, action, active_siblings)
-            if eligibility_error is not None:
-                return await session.redirect(get.projects.projects, error=eligibility_error)
-            existing = await data.approval_request(
-                project_key=str(project_key),
-                status_in=[sql.ApprovalStatus.PENDING, sql.ApprovalStatus.APPROVED],
-            ).get()
-            if existing is not None:
-                return await session.redirect(
-                    get.projects.projects,
-                    error=f"A CAP approval request to {existing.action.value} this project is already in progress.",
-                )
-
         closes_at = datetime.datetime.now(datetime.UTC) + datetime.timedelta(
             minutes=constants.CAP_VOTE_DURATION_MINUTES
         )
diff --git a/atr/post/vote.py b/atr/post/vote.py
index 71adfcf1..ffb7e56e 100644
--- a/atr/post/vote.py
+++ b/atr/post/vote.py
@@ -98,7 +98,9 @@ async def selected_post(  # noqa: C901
 
     async with storage.write(session) as write:
         wafc = write.as_foundation_committer()
-        email_to, error_message = await wafc.vote.send_user_vote(release, vote, comment, session.fullname, is_binding)
+        email_to, error_message = await wafc.vote.send_user_vote(
+            project_key, version_key, vote, comment, session.fullname, is_binding
+        )
 
     if error_message:
         await quart.flash(error_message, "error")
diff --git a/atr/post/voting.py b/atr/post/voting.py
index 554d2982..9c128b1a 100644
--- a/atr/post/voting.py
+++ b/atr/post/voting.py
@@ -211,7 +211,6 @@ async def selected(  # noqa: C901
                     subject,
                     start_voting_form.body,
                     session.fullname,
-                    release=release,
                     promote=True,
                     permitted_recipients=permitted_recipients,
                     email_cc=start_voting_form.email_cc,
@@ -334,7 +333,6 @@ async def _start_expedited(
                 subject,
                 start_voting_form.body,
                 session.fullname,
-                release=release,
                 promote=True,
                 expected_vote_mode=sql.VoteMode.TRUSTED,
                 expected_revision=start_voting_form.rendered_revision,
diff --git a/atr/sessions.py b/atr/sessions.py
index afab6627..215d8a51 100644
--- a/atr/sessions.py
+++ b/atr/sessions.py
@@ -57,8 +57,7 @@ async def account_check(session: sql.UserSession, current_time: float) -> None:
         await deleted_or_banned(uid)
         raise base.ASFQuartException("Account is disabled", errorcode=401)
 
-    session.last_account_check = current_time
-    await asfquart.APP.sessions.save(session, {"last_account_check"})
+    await asfquart.APP.sessions.save(session, {"last_account_check": current_time})
 
 
 async def deleted_or_banned(uid: str) -> None:
@@ -244,17 +243,20 @@ class Store:
                 await data.commit()
         return count
 
-    async def save(self, user_session: sql.UserSession, fields: set[MutableSessionField]) -> None:
-        if not fields.issubset(_MUTABLE_SESSION_FIELDS):
+    async def save(self, user_session: sql.UserSession, values: dict[MutableSessionField, float | bool | None]) -> None:
+        if not set(values).issubset(_MUTABLE_SESSION_FIELDS):
             raise ValueError("Invalid fields")
+        # The caller's copy is detached, cached on quart.g for the request, so update it as loaded state
+        for field, value in values.items():
+            db.set_committed_value(user_session, field, value)
         async with db.session() as data:
             statement = sqlmodel.select(sql.UserSession).where(sql.UserSession.sid_hash == user_session.sid_hash)
             result = await data.execute(statement)
             existing = result.scalar_one_or_none()
             if existing is None:
                 return
-            for field in fields:
-                setattr(existing, field, getattr(user_session, field))
+            for field, value in values.items():
+                setattr(existing, field, value)
             await data.commit()
 
     async def validate(self, hsid: str) -> sql.UserSession | None:
diff --git a/atr/storage/writers/vote.py b/atr/storage/writers/vote.py
index 0841a587..d37538ed 100644
--- a/atr/storage/writers/vote.py
+++ b/atr/storage/writers/vote.py
@@ -211,12 +211,19 @@ class FoundationCommitter(GeneralPublic):
 
     async def send_user_vote(
         self,
-        release: sql.Release,
+        project_key: safe.ProjectKey,
+        version_key: safe.VersionKey,
         vote: str,
         comment: str,
         fullname: str,
         is_binding: bool = False,
     ) -> tuple[list[str], str]:
+        release = await self.__data.release(
+            project_key=str(project_key),
+            version=str(version_key),
+            _project=True,
+            _committee=True,
+        ).demand(storage.AccessError("Release not found", status=404))
         storage.ensure_project_active(release.project)
         # Get the email thread
         latest_vote_task = await interaction.release_current_vote_task(release)
@@ -334,7 +341,6 @@ class ReleaseManager(CommitteeParticipant):
         subject: str,
         body_data: str,
         asf_fullname: str,
-        release: sql.Release | None = None,
         promote: bool = True,
         permitted_recipients: list[str] | None = None,
         email_cc: list[str] | None = None,
@@ -349,13 +355,12 @@ class ReleaseManager(CommitteeParticipant):
         download_path_suffix: safe.RelPath | None = None,
         acknowledged_concerns: frozenset[str] = frozenset(),
     ) -> sql.Task:
-        if release is None:
-            release = await self.__data.release(
-                project_key=str(project_key),
-                version=str(version_key),
-                _project=True,
-                _committee=True,
-            ).demand(storage.AccessError("Release not found", status=404))
+        release = await self.__data.release(
+            project_key=str(project_key),
+            version=str(version_key),
+            _project=True,
+            _committee=True,
+        ).demand(storage.AccessError("Release not found", status=404))
         storage.ensure_project_active(release.project)
         if release.expedited and (release.committee is not None) and release.committee.is_podling:
             raise storage.AccessError("Expedited releases are not available for podling projects", status=400)
@@ -815,7 +820,6 @@ class ReleaseManager(CommitteeParticipant):
                     vote_duration_choice=vote_duration,
                     subject=subject_data,
                     body_data=body_data,
-                    release=release,
                     promote=False,
                     expected_revision=release.safe_latest_revision_number,
                     automatic_resolve_when_finished=automatic_resolve_when_finished,
@@ -1148,7 +1152,6 @@ class ReleaseManager(CommitteeParticipant):
                     vote_duration_choice=vote_duration,
                     subject=subject_data,
                     body_data=body_data,
-                    release=release,
                     promote=False,
                     expected_revision=release.safe_latest_revision_number,
                     automatic_resolve_when_finished=automatic_resolve_when_finished,
diff --git a/scripts/lint/check_session_boundaries.py b/scripts/lint/check_session_boundaries.py
new file mode 100755
index 00000000..2d636da8
--- /dev/null
+++ b/scripts/lint/check_session_boundaries.py
@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Check session-context boundaries (issue #299).
+
+Two rules are checked:
+
+1. `async with db.session()` does not appear inside `async with storage.write*(...)`
+   or `async with storage.read*(...)`. The outer `storage.write/read` already
+   provides a session, and a separate inner session risks producing ORM objects
+   that outlive the inner block.
+
+2. Public methods in `atr/storage/writers/*.py` do not take `sql.X` table-model
+   types as parameters. Writers take `safe.X` keys and load the ORM object in their
+   own session. This applies only to names defined as
+   `class X(sqlmodel.SQLModel, table=True)` in `atr/models/sql.py`, so enums and
+   other value types in `sql` are fine. Return annotations are not checked.
+
+   `Callable[...]` subscripts are treated as opaque, as the callback pattern
+   hands ORM objects to a callback whose lifetime is bounded by the framework's
+   own session.
+
+With no arguments the whole of `atr/` is scanned, otherwise only the given paths.
+"""
+
+import ast
+import pathlib
+import sys
+from typing import Final
+
+_DEFAULT_PATH: Final = pathlib.Path(__file__).parent.parent.parent / "atr"
+_SQL_MODELS_PATH: Final = pathlib.Path(__file__).parent.parent.parent / "atr" / "models" / "sql.py"
+_WRITERS_DIR_FRAGMENT: Final = "atr/storage/writers/"
+_CALLABLE_NAMES: Final = frozenset({"Callable", "typing.Callable", "collections.abc.Callable"})
+
+
+def main() -> None:
+    sys.exit(_run(sys.argv[1:]))
+
+
+def _annotation_references_table_model(annotation: ast.AST | None, table_models: frozenset[str]) -> bool:
+    if annotation is None:
+        return False
+    if isinstance(annotation, ast.Subscript) and _is_callable(annotation.value):
+        return False
+    if isinstance(annotation, (ast.Name, ast.Attribute)):
+        name = _name(annotation)
+        if name and any((name == f"sql.{model}") or name.endswith(f".sql.{model}") for model in table_models):
+            return True
+    for child in ast.iter_child_nodes(annotation):
+        if _annotation_references_table_model(child, table_models):
+            return True
+    return False
+
+
+def _check_file(path: pathlib.Path, table_models: frozenset[str]) -> list[str]:
+    tree = ast.parse(path.read_text(), filename=str(path))
+    errors: list[str] = []
+    _check_session_nesting(path, tree, False, errors)
+    if _is_writer_module(path):
+        errors.extend(_check_writer_signatures(path, tree, table_models))
+    return errors
+
+
+def _check_session_nesting(path: pathlib.Path, node: ast.AST, in_storage: bool, errors: list[str]) -> None:
+    if isinstance(node, ast.AsyncWith):
+        opens_storage = any(_is_storage_context_call(item.context_expr) for item in node.items)
+        opens_db_session = any(_is_db_session_call(item.context_expr) for item in node.items)
+        if in_storage and opens_db_session:
+            errors.append(f"{path}:{node.lineno}: db.session() opened inside storage.write/read context")
+        next_in_storage = in_storage or opens_storage
+        for child in ast.iter_child_nodes(node):
+            _check_session_nesting(path, child, next_in_storage, errors)
+        return
+    for child in ast.iter_child_nodes(node):
+        _check_session_nesting(path, child, in_storage, errors)
+
+
+def _check_signature(
+    path: pathlib.Path,
+    cls: ast.ClassDef,
+    func: ast.FunctionDef | ast.AsyncFunctionDef,
+    table_models: frozenset[str],
+) -> list[str]:
+    errors: list[str] = []
+    for arg in (*func.args.posonlyargs, *func.args.args, *func.args.kwonlyargs):
+        if _annotation_references_table_model(arg.annotation, table_models):
+            errors.append(
+                f"{path}:{arg.lineno}: {cls.name}.{func.name} parameter '{arg.arg}' has sql.* table-model type"
+            )
+    return errors
+
+
+def _check_writer_signatures(path: pathlib.Path, tree: ast.AST, table_models: frozenset[str]) -> list[str]:
+    errors: list[str] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ClassDef):
+            continue
+        for member in node.body:
+            if not isinstance(member, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            if member.name.startswith("_"):
+                continue
+            errors.extend(_check_signature(path, node, member, table_models))
+    return errors
+
+
+def _files(argv: list[str]) -> list[pathlib.Path]:
+    if not argv:
+        return _python_files(_DEFAULT_PATH)
+    paths: list[pathlib.Path] = []
+    for arg in argv:
+        path = pathlib.Path(arg)
+        if path.is_dir():
+            paths.extend(_python_files(path))
+        else:
+            paths.append(path)
+    return paths
+
+
+def _is_callable(value: ast.expr) -> bool:
+    name = _name(value)
+    return (name is not None) and (name in _CALLABLE_NAMES)
+
+
+def _is_db_session_call(value: ast.expr) -> bool:
+    return isinstance(value, ast.Call) and (_name(value.func) == "db.session")
+
+
+def _is_storage_context_call(value: ast.expr) -> bool:
+    if not isinstance(value, ast.Call):
+        return False
+    name = _name(value.func)
+    if name is None:
+        return False
+    if not name.startswith("storage."):
+        return False
+    method = name.removeprefix("storage.")
+    return method.startswith("write") or method.startswith("read")
+
+
+def _is_table_model(node: ast.ClassDef) -> bool:
+    if "sqlmodel.SQLModel" not in {_name(base) for base in node.bases}:
+        return False
+    for keyword in node.keywords:
+        if (keyword.arg == "table") and isinstance(keyword.value, ast.Constant) and (keyword.value.value is True):
+            return True
+    return False
+
+
+def _is_writer_module(path: pathlib.Path) -> bool:
+    return _WRITERS_DIR_FRAGMENT in str(path).replace("\\", "/")
+
+
+def _name(value: ast.expr) -> str | None:
+    if isinstance(value, ast.Name):
+        return value.id
+    if isinstance(value, ast.Attribute):
+        parent = _name(value.value)
+        if parent is None:
+            return value.attr
+        return f"{parent}.{value.attr}"
+    return None
+
+
+def _python_files(directory: pathlib.Path) -> list[pathlib.Path]:
+    return sorted(directory.rglob("*.py"))
+
+
+def _run(argv: list[str]) -> int:
+    table_models = _table_model_names()
+    errors: list[str] = []
+    for path in _files(argv):
+        errors.extend(_check_file(path, table_models))
+    for error in errors:
+        print(error, file=sys.stderr)
+    return 1 if errors else 0
+
+
+def _table_model_names() -> frozenset[str]:
+    tree = ast.parse(_SQL_MODELS_PATH.read_text(), filename=str(_SQL_MODELS_PATH))
+    result: set[str] = set()
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef) and _is_table_model(node):
+            result.add(node.name)
+    return frozenset(result)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/unit/test_session_guards.py b/tests/unit/test_session_guards.py
new file mode 100644
index 00000000..10971911
--- /dev/null
+++ b/tests/unit/test_session_guards.py
@@ -0,0 +1,171 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+import datetime
+from collections.abc import AsyncIterator
+
+import pytest
+import sqlalchemy
+import sqlalchemy.ext.asyncio
+import sqlalchemy.pool
+import sqlmodel
+
+import atr.db as db
+import atr.models.sql as sql
+
+type Maker = sqlalchemy.ext.asyncio.async_sessionmaker[db.Session]
+
+
+@pytest.fixture
+async def maker() -> AsyncIterator[Maker]:
+    db.install_detached_mutation_guard()
+    engine = sqlalchemy.ext.asyncio.create_async_engine(
+        "sqlite+aiosqlite:///:memory:",
+        connect_args={"check_same_thread": False},
+        poolclass=sqlalchemy.pool.StaticPool,
+    )
+    async with engine.begin() as conn:
+        await conn.run_sync(sqlmodel.SQLModel.metadata.create_all)
+    sessionmaker = sqlalchemy.ext.asyncio.async_sessionmaker(bind=engine, class_=db.Session, expire_on_commit=False)
+    async with sessionmaker() as data:
+        data.add(sql.Committee(key="tooling", name="Tooling"))
+        project = sql.Project(key="tooling-atr", name="Apache Tooling ATR", committee_key="tooling")
+        data.add(project)
+        await data.commit()
+        data.add(sql.ReleasePolicy(project=project, min_hours=24))
+        data.add(_release("0.1.0"))
+        await data.commit()
+    yield sessionmaker
+    await engine.dispose()
+
+
+async def test_aexit_keeps_exception_from_block(maker: Maker) -> None:
+    with pytest.raises(ValueError, match="boom"):
+        async with maker() as data:
+            project = await _project(data)
+            project.description = "changed"
+            raise ValueError("boom")
+
+
+async def test_aexit_raises_for_uncommitted_change(maker: Maker) -> None:
+    with pytest.raises(db.UnflushedChangesError, match="Project"):
+        async with maker() as data:
+            project = await _project(data)
+            project.description = "first"
+            await data.commit()
+            project.description = "second"
+    async with maker() as data:
+        assert (await _project(data)).description == "first"
+
+
+async def test_aexit_allows_explicit_rollback(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+        project.description = "changed"
+        await data.rollback()
+
+
+async def test_aexit_allows_no_op_assignment(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+        project.description = project.description
+
+
+async def test_aexit_allows_read_only_block(maker: Maker) -> None:
+    async with maker() as data:
+        await _project(data)
+
+
+async def test_detached_mutation_names_written_attribute(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+    with pytest.raises(db.DetachedMutationError, match=r"Project.description"):
+        project.description = "changed"
+
+
+async def test_detached_mutation_raises_across_sessions(maker: Maker) -> None:
+    async with maker() as data:
+        project = await data.project(key="tooling-atr", _release_policy=True).demand(RuntimeError("no project"))
+    async with maker() as writer_data:
+        with pytest.raises(db.DetachedMutationError, match=r"ReleasePolicy.min_hours"):
+            project.release_policy.min_hours = 72
+        await writer_data.commit()
+    async with maker() as data:
+        project = await data.project(key="tooling-atr", _release_policy=True).demand(RuntimeError("no project"))
+        assert project.release_policy.min_hours == 24
+
+
+async def test_detached_mutation_names_origin_of_backref_write(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+        release = await data.release(project_key="tooling-atr", version="0.1.0").demand(RuntimeError("no release"))
+    with pytest.raises(db.DetachedMutationError, match=r"Release.project"):
+        release.project = project
+
+
+async def test_merge_then_mutate_lands(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+    async with maker() as data:
+        merged = await data.merge(project)
+        merged.description = "merged"
+        await data.commit()
+    async with maker() as data:
+        assert (await _project(data)).description == "merged"
+
+
+async def test_mutate_after_commit_inside_block_lands(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+        await data.commit()
+        project.description = "after commit"
+        await data.commit()
+    async with maker() as data:
+        assert (await _project(data)).description == "after commit"
+
+
+async def test_set_committed_value_does_not_dirty_detached_instance(maker: Maker) -> None:
+    async with maker() as data:
+        project = await _project(data)
+        release = await data.release(project_key="tooling-atr", version="0.1.0").demand(RuntimeError("no release"))
+    db.set_committed_value(release, "project", project)
+    assert release.project is project
+    assert not sqlalchemy.inspect(release).modified
+
+
+async def test_transient_construct_and_commit_works(maker: Maker) -> None:
+    async with maker() as data:
+        release = _release("0.2.0")
+        release.phase = sql.ReleasePhase.RELEASE_CANDIDATE
+        data.add(release)
+        await data.commit()
+    async with maker() as data:
+        stored = await data.release(project_key="tooling-atr", version="0.2.0").demand(RuntimeError("no release"))
+        assert stored.phase == sql.ReleasePhase.RELEASE_CANDIDATE
+
+
+async def _project(data: db.Session) -> sql.Project:
+    return await data.project(key="tooling-atr").demand(RuntimeError("no project"))
+
+
+def _release(version: str) -> sql.Release:
+    return sql.Release(
+        project_key="tooling-atr",
+        version=version,
+        phase=sql.ReleasePhase.RELEASE_CANDIDATE_DRAFT,
+        created=datetime.datetime.now(datetime.UTC),
+    )
diff --git a/tests/unit/test_sessions.py b/tests/unit/test_sessions.py
index b4b6e85d..745ce691 100644
--- a/tests/unit/test_sessions.py
+++ b/tests/unit/test_sessions.py
@@ -74,8 +74,7 @@ async def test_account_check_fails_open_when_ldap_unavailable(monkeypatch):
     await sessions.account_check(user_session, 123.0)
 
     deleted.assert_not_awaited()
-    save.assert_awaited_once()
-    assert user_session.last_account_check == 123.0
+    save.assert_awaited_once_with(user_session, {"last_account_check": 123.0})
 
 
 async def test_account_check_revokes_user_when_admin_check_unavailable(monkeypatch):
@@ -104,8 +103,7 @@ async def test_account_check_saves_timestamp_when_active(monkeypatch):
 
     await sessions.account_check(user_session, 123.0)
 
-    save.assert_awaited_once()
-    assert user_session.last_account_check == 123.0
+    save.assert_awaited_once_with(user_session, {"last_account_check": 123.0})
 
 
 async def test_create_logs_auth_success(store, monkeypatch):
@@ -205,7 +203,7 @@ async def test_destroy_then_save_does_not_resurrect(store):
     assert user_session is not None
 
     await store.destroy(hsid)
-    await store.save(user_session, {"last_account_check"})
+    await store.save(user_session, {"last_account_check": 12345.0})
     assert await store.validate(hsid) is None
 
 
@@ -280,14 +278,14 @@ async def test_revoke_by_uid_removes_all_sessions(store):
     assert await store.validate(hsid3) is not None
 
 
-async def test_save_persists_mutations(store):
+async def test_save_persists_values(store):
     hsid = _hsid()
     await store.create(hsid, _session_data())
     user_session = await store.validate(hsid)
     assert user_session is not None
 
-    user_session.last_account_check = 12345.0
-    await store.save(user_session, {"last_account_check"})
+    await store.save(user_session, {"last_account_check": 12345.0})
+    assert user_session.last_account_check == 12345.0
 
     reloaded = await store.validate(hsid)
     assert reloaded is not None
diff --git a/tests/unit/test_svn_publish_start_vote.py b/tests/unit/test_svn_publish_start_vote.py
index a8a36cb0..5bdb7586 100644
--- a/tests/unit/test_svn_publish_start_vote.py
+++ b/tests/unit/test_svn_publish_start_vote.py
@@ -168,6 +168,7 @@ async def test_start_rejects_automatic_publish_for_expedited(monkeypatch) -> Non
         expedited=True,
         podling_thread_id=None,
     )
+    data.release = mock.MagicMock(return_value=SimpleNamespace(demand=mock.AsyncMock(return_value=release)))
     data.project = mock.MagicMock(
         return_value=SimpleNamespace(get=mock.AsyncMock(return_value=SimpleNamespace(committee=committee)))
     )
@@ -191,7 +192,6 @@ async def test_start_rejects_automatic_publish_for_expedited(monkeypatch) -> Non
             "[VOTE] Release example 1.0",
             "Please vote.",
             "Alice",
-            release=release,
             promote=True,
             automatic_publish_when_resolved=True,
         )
diff --git a/tests/unit/test_vote_serials.py b/tests/unit/test_vote_serials.py
index 5d83afb2..1bba5094 100644
--- a/tests/unit/test_vote_serials.py
+++ b/tests/unit/test_vote_serials.py
@@ -474,7 +474,6 @@ async def test_podling_second_round_rolls_back_with_task_creation(sqlite_session
                     vote_duration_choice=72,
                     subject="[VOTE] Release",
                     body_data="Please vote",
-                    release=release_model,
                     promote=False,
                 )
                 assert task.task_args["vote_seq"] == 2
@@ -658,7 +657,9 @@ async def test_vote_email_labels_reflect_membership(
             is_binding, _committee = await user.is_binding_for_release(
                 release_model.project.committee, "chair", vote_round, caller_data=data
             )
-            result = await writer.send_user_vote(release_model, "+1", "", "Voter", is_binding)
+            result = await writer.send_user_vote(
+                safe.ProjectKey("project"), safe.VersionKey("1.0.0"), "+1", "", "Voter", is_binding
+            )
 
         assert result == (["dev@project.apache.org"], "")
         message_task = (


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org


(tooling-trusted-releases) 02/02: #299 - Documentation of session detachment and good practice

Posted by ar...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

alitheg pushed a commit to branch 299
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git

commit 6e03dae6f08a802fea1479f7d12215da084c2fe5
Author: Alastair McFarlane <ar...@apache.org>
AuthorDate: Tue Oct 20 12:37:31 2026 +0100

    #299 - Documentation of session detachment and good practice
---
 atr/docs/database.md          | 26 ++++++++++++++++++++++++++
 atr/docs/storage-interface.md |  5 +++++
 2 files changed, 31 insertions(+)

diff --git a/atr/docs/database.md b/atr/docs/database.md
index 86a2bd0a..6a4ed525 100644
--- a/atr/docs/database.md
+++ b/atr/docs/database.md
@@ -160,6 +160,32 @@ unique constraint on `(project_key, version)` to prevent creating duplicate rele
 project version. The `Revision` model has two unique constraints: one on `(release_key, seq)` and
 another on `(release_key, number)`, ensuring that revision numbers are unique within a release.
 
+### Sessions and detached objects
+
+A session lasts for its `async with` block. Objects loaded in a `db.session()` or `storage.write()`
+block are attached to that session and detached once it ends. Column values on a detached object can
+still be read, because sessions are created with `expire_on_commit=False`, but nothing else about a
+detached object works.
+
+Assigning to a detached object raises
+[`db.DetachedMutationError`](/ref/atr/db/__init__.py) (DetachedMutationError), as the write would
+otherwise be discarded. Leaving a block with uncommitted changes raises
+[`db.UnflushedChangesError`](/ref/atr/db/__init__.py) (UnflushedChangesError), as they would
+otherwise be rolled back. Reading a relationship that was not eager loaded raises in SQLAlchemy, so
+the query helpers on [`db.Session`](/ref/atr/db/__init__.py) (Session) take flags such as
+`_project=True` to load what callers will read.
+
+Writers' arguments use keys like `safe.ProjectKey` and load the object in their own session, rather than
+accepting an ORM object from another block. `await data.merge(obj)` attaches a copy of an object to
+the current session when one has to be carried across. To make a related object available for
+rendering, such as `release.project` when the handler already holds the project,
+[`db.set_committed_value(release, "project", project)`](/ref/atr/db/__init__.py)
+(set_committed_value) sets it as loaded state without marking anything dirty.
+
+The `check-session-boundaries` pre-commit hook rejects a `db.session()` opened inside a
+`storage.write()` or `storage.read()` block, and public writer methods that take a `sql` table model
+as a parameter.
+
 ## Cascade deletions
 
 ATR uses two kinds of cascade deletions: ORM-level cascades managed by SQLAlchemy, and DB-level
diff --git a/atr/docs/storage-interface.md b/atr/docs/storage-interface.md
index 7ca65a21..eabc9dfb 100644
--- a/atr/docs/storage-interface.md
+++ b/atr/docs/storage-interface.md
@@ -73,6 +73,11 @@ from the current request context. The write object checks LDAP memberships and r
 [`storage.AccessError`](/ref/atr/storage/__init__.py) (AccessError) if the user is not authorized
 for the requested permission level.
 
+The writer's database session lasts for the `async with` block. Anything a writer returns is
+attached while the block is open and detached once it ends, so read
+[Sessions and detached objects](database#sessions-and-detached-objects) before holding on to a
+returned object past the end of the block.
+
 Because projects belong to committees, we provide
 [`write.as_project_committee_member(project_name)`](/ref/atr/storage/__init__.py)
 (as_project_committee_member) and


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org