velocity-python 0.1.87__tar.gz → 0.1.88__tar.gz

{velocity_python-0.1.87/src/velocity_python.egg-info → velocity_python-0.1.88}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.87
+Version: 0.1.88
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.87 → velocity_python-0.1.88}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.87"
+version = "0.1.88"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.1.87 → velocity_python-0.1.88}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.87"
+__version__ = version = "0.1.88"
 
 import importlib as _importlib
 

{velocity_python-0.1.87 → velocity_python-0.1.88}/src/velocity/aws/handlers/context.py

@@ -485,13 +485,43 @@ class Context:
     def was_job_cancelled(self):
         return self._job_cancelled_flag
 
-    def enqueue(self, action, payload={}, user=None, suppress_job_activity=False):
+    def enqueue(
+        self,
+        action,
+        payload={},
+        user=None,
+        suppress_job_activity=False,
+        transaction=None,
+    ):
         """
         Enqueue jobs to SQS with independent job activity tracking.
 
         This method uses its own transaction for aws_job_activity updates to ensure
         job tracking is never rolled back with other operations.
+
+        When ``transaction`` (a velocity Transaction) is provided, the entire
+        enqueue — job-activity bookkeeping and the SQS send — is deferred until
+        that transaction commits, via ``Transaction.on_commit``. Use this
+        whenever the queued job will read back rows written in the same
+        transaction: sending immediately races the SQS consumer against the
+        COMMIT, and the consumer can win and find nothing (this dropped a
+        production Braintree webhook). If the transaction rolls back, nothing
+        is enqueued.
+
+        (The parameter is named ``transaction`` rather than ``tx`` because the
+        ``@engine.transaction`` class decorator auto-wraps any method with a
+        ``tx`` parameter and would inject its own transaction here.)
         """
+        if transaction is not None:
+            transaction.on_commit(
+                lambda: self.enqueue(
+                    action,
+                    payload=payload,
+                    user=user,
+                    suppress_job_activity=suppress_job_activity,
+                )
+            )
+            return {"deferred_until_commit": True}
         batch_id = str(uuid.uuid4())
         results = {"batch_id": batch_id}
         queue = boto3.resource("sqs").get_queue_by_name(

{velocity_python-0.1.87 → velocity_python-0.1.88}/src/velocity/db/core/engine.py

@@ -650,6 +650,12 @@ class Engine:
                 loop_start = time.perf_counter()
                 while True:
                     try:
+                        # Each attempt must start with no stale on_commit
+                        # callbacks from a previous failed attempt — not every
+                        # retry path rolls back (the transient-connection path
+                        # discards the connection instead), and the re-run
+                        # function registers its own callbacks again.
+                        _tx.discard_on_commit_callbacks()
                         result = function(*args, **kwds)
                         # Commit INSIDE the retry envelope so a commit-time
                         # serialization failure / deadlock / deferred-constraint

{velocity_python-0.1.87 → velocity_python-0.1.88}/src/velocity/db/core/transaction.py

@@ -194,6 +194,12 @@ class Transaction:
         # fresh transaction and lose the prior uncommitted statements without
         # any error. Reset on connect/commit/rollback.
         self._in_progress = False
+        # R32 — Callables to run once, after the transaction's work is durably
+        # committed (see on_commit()). Discarded on rollback and whenever a
+        # dead connection is dropped, so callbacks from a failed attempt never
+        # fire; the @engine.transaction retry envelope also clears them before
+        # each attempt so a re-run function re-registers from a clean slate.
+        self._on_commit_callbacks = []
 
     def __str__(self):
         config = mask_config_for_display(self.engine.config)
@@ -248,6 +254,9 @@ class Transaction:
         dead = self.connection
         self.connection = None
         self._in_progress = False
+        # Uncommitted work is gone; anything queued to run after its commit
+        # must never fire.
+        self._on_commit_callbacks = []
         if dead is None:
             return
         if self.__pooled:
@@ -306,6 +315,9 @@ class Transaction:
         the pool instead of being closed.
         """
         if not self.connection:
+            # No DB work happened, so there is nothing to commit — but the
+            # transaction still completed; run any on_commit callbacks.
+            self._fire_on_commit_callbacks()
             return
         if debug:
             print(f"<<< {id(self)} close connection.")
@@ -565,6 +577,67 @@ class Transaction:
                         "query_time_ms": round(self._query_time_ms, 1),
                     },
                 )
+        # Fire after the DB work is durable (or when there was no DB work at
+        # all — a transaction that only registered callbacks still completes).
+        # A commit-time DB error raises above, so callbacks from a failed
+        # commit never run here.
+        self._fire_on_commit_callbacks()
+
+    def on_commit(self, callback):
+        """Register a callable to run once, after this transaction commits.
+
+        Use this for side effects that must not become visible before the
+        transaction's DB work does — e.g. sending an SQS message that a
+        consumer will immediately read back from the database. Sending inside
+        the open transaction races the consumer against the commit; deferring
+        with ``on_commit`` closes that race::
+
+            @engine.transaction
+            def handler(tx, context):
+                row = tx.table("webhooks").new({...})
+                tx.on_commit(lambda: context.enqueue(..., payload={"webhook_id": row.sys_id}))
+
+        Semantics:
+
+        * Callbacks run in registration order, once, immediately after a
+          successful COMMIT (``commit()``/``close()``/decorator exit). If the
+          transaction never touched the database, they run when it completes.
+        * They are discarded — never run — on ``rollback()``, when a dead
+          connection is dropped, and before each ``@engine.transaction`` retry
+          attempt (the re-run function registers its own again).
+        * A callback exception is logged and does not propagate: the commit is
+          already durable, so raising would misreport a committed transaction
+          as failed (and e.g. make a webhook caller retry a done request).
+          Callbacks needing delivery guarantees must handle their own errors.
+        """
+        if not callable(callback):
+            raise TypeError("on_commit callback must be callable")
+        # getattr-guarded: some tests (and potential subclasses) build a
+        # Transaction without running __init__.
+        callbacks = getattr(self, "_on_commit_callbacks", None)
+        if callbacks is None:
+            callbacks = self._on_commit_callbacks = []
+        callbacks.append(callback)
+        return callback
+
+    def discard_on_commit_callbacks(self):
+        """Drop any registered on_commit callbacks without running them."""
+        self._on_commit_callbacks = []
+
+    def _fire_on_commit_callbacks(self):
+        callbacks = getattr(self, "_on_commit_callbacks", None)
+        self._on_commit_callbacks = []
+        if not callbacks:
+            return
+        for callback in callbacks:
+            try:
+                callback()
+            except Exception:
+                _logger.exception(
+                    "on_commit callback %r failed; the transaction is already "
+                    "committed, so the error is logged and not raised",
+                    callback,
+                )
 
     def rollback(self):
         """
@@ -576,6 +649,8 @@ class Transaction:
             self.connection.rollback()
             # Transaction is clean again — no uncommitted work pending.
             self._in_progress = False
+        # The work these were waiting on is rolled back — never run them.
+        self._on_commit_callbacks = []
 
     def is_aborted(self):
         """Return True if the connection is in a failed/aborted transaction.

{velocity_python-0.1.87 → velocity_python-0.1.88/src/velocity_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.87
+Version: 0.1.88
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.87 → velocity_python-0.1.88}/src/velocity_python.egg-info/SOURCES.txt

@@ -219,6 +219,7 @@ tests/test_nosql_redis.py
 tests/test_nosql_translation.py
 tests/test_nosql_where.py
 tests/test_observability.py
+tests/test_on_commit.py
 tests/test_payment_authorizenet_adapter.py
 tests/test_payment_braintree_adapter.py
 tests/test_payment_braintree_mirror.py

velocity_python-0.1.88/tests/test_on_commit.py

@@ -0,0 +1,216 @@
+"""Transaction.on_commit and Context.enqueue(tx=...) — post-commit side effects.
+
+Motivation: sending an SQS message inside a still-open transaction races the
+consumer against the COMMIT; the consumer can read the database before the
+producer's rows are visible (this dropped a production Braintree webhook).
+``tx.on_commit`` defers such side effects until the work is durable, and
+``Context.enqueue(..., transaction=tx)`` uses it to defer the whole enqueue.
+"""
+
+import unittest
+from unittest.mock import MagicMock, patch
+
+from velocity.db import exceptions
+from velocity.db.core.engine import Engine
+from velocity.db.core.transaction import Transaction
+from velocity.aws.handlers import context as handler_context
+
+
+def _make_tx(connection=None):
+    engine = MagicMock()
+    engine.pool_enabled = False
+    connection = connection if connection is not None else MagicMock()
+    return Transaction(engine, connection), connection
+
+
+class TransactionOnCommitTests(unittest.TestCase):
+    def test_callbacks_fire_in_order_after_commit(self):
+        tx, _ = _make_tx()
+        fired = []
+        tx.on_commit(lambda: fired.append("first"))
+        tx.on_commit(lambda: fired.append("second"))
+        self.assertEqual([], fired)  # nothing runs before commit
+        tx.commit()
+        self.assertEqual(["first", "second"], fired)
+
+    def test_callbacks_fire_only_once(self):
+        tx, _ = _make_tx()
+        fired = []
+        tx.on_commit(lambda: fired.append(1))
+        tx.commit()
+        tx.commit()  # e.g. close() after an explicit commit
+        self.assertEqual([1], fired)
+
+    def test_rollback_discards_callbacks(self):
+        tx, _ = _make_tx()
+        fired = []
+        tx.on_commit(lambda: fired.append(1))
+        tx.rollback()
+        tx.commit()
+        self.assertEqual([], fired)
+
+    def test_close_without_db_work_still_fires(self):
+        tx, _ = _make_tx(connection=False)
+        tx.connection = None  # transaction never touched the database
+        fired = []
+        tx.on_commit(lambda: fired.append(1))
+        tx.close()
+        self.assertEqual([1], fired)
+
+    def test_commit_time_db_error_does_not_fire(self):
+        tx, connection = _make_tx()
+        connection.commit.side_effect = RuntimeError("deadlock at COMMIT")
+        tx.engine.process_error.side_effect = lambda e: exceptions.DbRetryTransaction(
+            str(e)
+        )
+        fired = []
+        tx.on_commit(lambda: fired.append(1))
+        with self.assertRaises(exceptions.DbRetryTransaction):
+            tx.commit()
+        self.assertEqual([], fired)
+        # The retry envelope rolls back next; the callback must stay discarded.
+        tx.rollback()
+        connection.commit.side_effect = None
+        tx.commit()
+        self.assertEqual([], fired)
+
+    def test_callback_exception_is_swallowed_and_rest_run(self):
+        tx, _ = _make_tx()
+        fired = []
+
+        def _explodes():
+            raise ValueError("boom")
+
+        tx.on_commit(_explodes)
+        tx.on_commit(lambda: fired.append("still ran"))
+        with self.assertLogs("velocity.db.transaction", level="ERROR"):
+            tx.commit()
+        self.assertEqual(["still ran"], fired)
+
+    def test_dead_connection_discard_clears_callbacks(self):
+        tx, _ = _make_tx()
+        fired = []
+        tx.on_commit(lambda: fired.append(1))
+        tx._discard_dead_connection()
+        tx.commit()
+        self.assertEqual([], fired)
+
+    def test_non_callable_rejected(self):
+        tx, _ = _make_tx()
+        with self.assertRaises(TypeError):
+            tx.on_commit("not callable")
+
+
+class ExecFunctionRetryTests(unittest.TestCase):
+    def test_retry_attempt_does_not_replay_previous_attempts_callbacks(self):
+        """A failed attempt's callbacks must never fire; only the committed
+        attempt's do — and exactly once."""
+        tx, _ = _make_tx()
+        engine = MagicMock()
+        engine.MAX_RETRIES = 3
+        fired = []
+        attempts = {"n": 0}
+
+        def function():
+            attempts["n"] += 1
+            attempt = attempts["n"]
+            tx.on_commit(lambda: fired.append(attempt))
+            if attempt == 1:
+                raise exceptions.DbRetryTransaction("serialization failure")
+
+        with patch("velocity.db.core.engine.time.sleep"):
+            Engine.exec_function(engine, function, tx, _owns_tx=True)
+
+        self.assertEqual(2, attempts["n"])
+        self.assertEqual([2], fired)  # attempt 1's callback discarded
+
+
+class EnqueueDeferredTests(unittest.TestCase):
+    class _FakeQueue:
+        def __init__(self):
+            self.sent = []
+
+        def send_messages(self, Entries):
+            self.sent.extend(Entries)
+            return {"Successful": [{"Id": e["Id"]} for e in Entries], "Failed": []}
+
+    class _FakeContext:
+        def __init__(self):
+            self.jobs = []
+
+        def session(self):
+            return {"email_address": "owner@example.com"}
+
+        def create_job(self, job_data=None):
+            self.jobs.append(job_data)
+
+        def fail_enqueue(self, **kwargs):
+            raise AssertionError("no send failures expected")
+
+        # Bind the real method so the deferred callback re-enters it.
+        enqueue = handler_context.Context.enqueue
+
+    def _patched(self, queue):
+        class _Resource:
+            def get_queue_by_name(self, QueueName):
+                return queue
+
+        return (
+            patch.dict(
+                handler_context.os.environ,
+                {"SqsWorkQueue": "example-queue"},
+                clear=False,
+            ),
+            patch.object(handler_context.boto3, "resource", return_value=_Resource()),
+        )
+
+    def test_enqueue_with_tx_defers_until_commit(self):
+        ctx = self._FakeContext()
+        queue = self._FakeQueue()
+        tx, _ = _make_tx()
+
+        env_patch, boto_patch = self._patched(queue)
+        with env_patch, boto_patch:
+            result = ctx.enqueue(
+                "process-braintree-webhook",
+                payload={"webhook_id": 1116},
+                transaction=tx,
+            )
+            # Nothing sent or tracked while the transaction is open.
+            self.assertEqual({"deferred_until_commit": True}, result)
+            self.assertEqual([], queue.sent)
+            self.assertEqual([], ctx.jobs)
+
+            tx.commit()
+
+        self.assertEqual(1, len(queue.sent))
+        self.assertEqual(1, len(ctx.jobs))
+        self.assertIn("process-braintree-webhook", queue.sent[0]["MessageBody"])
+
+    def test_enqueue_with_tx_rollback_sends_nothing(self):
+        ctx = self._FakeContext()
+        queue = self._FakeQueue()
+        tx, _ = _make_tx()
+
+        env_patch, boto_patch = self._patched(queue)
+        with env_patch, boto_patch:
+            ctx.enqueue("some-action", payload={"x": 1}, transaction=tx)
+            tx.rollback()
+            tx.commit()
+
+        self.assertEqual([], queue.sent)
+        self.assertEqual([], ctx.jobs)
+
+    def test_enqueue_without_tx_sends_immediately(self):
+        ctx = self._FakeContext()
+        queue = self._FakeQueue()
+
+        env_patch, boto_patch = self._patched(queue)
+        with env_patch, boto_patch:
+            ctx.enqueue("some-action", payload={"x": 1})
+
+        self.assertEqual(1, len(queue.sent))
+
+
+if __name__ == "__main__":
+    unittest.main()