feat: make errors more informative

emptybutton · emptybutton · commit 370fd11d14e1 · 2025-06-06T21:04:50.000+07:00
diff --git a/src/tgdb/application/horizon/commit_transaction.py b/src/tgdb/application/horizon/commit_transaction.py
@@ -41,7 +41,7 @@ async def __call__(
         """
         :raises tgdb.application.relation.ports.relations.NoRelationError:
         :raises tgdb.entities.horizon.horizon.NoTransactionError:
-        :raises tgdb.entities.horizon.horizon.InvalidTransactionStateError:
+        :raises tgdb.entities.horizon.horizon.TransactionCommittingError:
         :raises tgdb.entities.horizon.transaction.ConflictError:
         """
 
diff --git a/src/tgdb/application/horizon/output_commits.py b/src/tgdb/application/horizon/output_commits.py
@@ -7,8 +7,8 @@
 from tgdb.application.horizon.ports.channel import Channel
 from tgdb.application.horizon.ports.shared_horizon import SharedHorizon
 from tgdb.entities.horizon.horizon import (
-    InvalidTransactionStateError,
     NoTransactionError,
+    TransactionNotCommittingError,
 )
 from tgdb.entities.horizon.transaction import XID, Commit, PreparedCommit
 
@@ -28,7 +28,7 @@ async def __call__(self) -> None:
 
             ok_commit_xids = list[XID]()
             error_commit_map = dict[
-                XID, NoTransactionError | InvalidTransactionStateError
+                XID, NoTransactionError | TransactionNotCommittingError
             ]()
 
             async with self.shared_horizon as horizon:
@@ -38,7 +38,7 @@ async def __call__(self) -> None:
                     try:
                         horizon.complete_commit(time, prepared_commit.xid)
                     except (
-                        NoTransactionError, InvalidTransactionStateError
+                        NoTransactionError, TransactionNotCommittingError
                     ) as error:
                         error_commit_map[prepared_commit.xid] = error
                     else:
diff --git a/src/tgdb/application/horizon/ports/channel.py b/src/tgdb/application/horizon/ports/channel.py
@@ -3,15 +3,15 @@
 from dataclasses import dataclass
 
 from tgdb.entities.horizon.horizon import (
-    InvalidTransactionStateError,
     NoTransactionError,
+    TransactionNotCommittingError,
 )
 from tgdb.entities.horizon.transaction import XID
 
 
 @dataclass(frozen=True)
 class Notification:
-    error: NoTransactionError | InvalidTransactionStateError | None
+    error: NoTransactionError | TransactionNotCommittingError | None
 
 
 class Channel(ABC):
@@ -20,7 +20,7 @@ async def publish(
         self,
         ok_commit_xids: Sequence[XID],
         error_commit_map: Mapping[
-            XID, NoTransactionError | InvalidTransactionStateError
+            XID, NoTransactionError | TransactionNotCommittingError
         ],
         /,
     ) -> None: ...
diff --git a/src/tgdb/application/horizon/rollback_transaction.py b/src/tgdb/application/horizon/rollback_transaction.py
@@ -15,6 +15,7 @@ class RollbackTransaction:
     async def __call__(self, xid: XID) -> None:
         """
         :raises tgdb.entities.horizon.horizon.NoTransactionError:
+        :raises tgdb.entities.horizon.horizon.TransactionCommittingError:
         """
 
         time = await self.clock
diff --git a/src/tgdb/application/horizon/start_transaction.py b/src/tgdb/application/horizon/start_transaction.py
@@ -16,10 +16,6 @@ class StartTransaction:
     clock: Clock
 
     async def __call__(self, isolation_level: IsolationLevel) -> XID:
-        """
-        :raises tgdb.entities.horizon.horizon.InvalidTransactionStateError:
-        """
-
         time = await self.clock
         xid = await self.uuids.random_uuid()
 
diff --git a/src/tgdb/application/relation/view_tuples.py b/src/tgdb/application/relation/view_tuples.py
@@ -30,7 +30,7 @@ async def __call__(
         """
         :raises tgdb.application.relation.ports.relations.NoRelationError:
         :raises tgdb.entities.horizon.horizon.NoTransactionError:
-        :raises tgdb.entities.horizon.horizon.InvalidTransactionStateError:
+        :raises tgdb.entities.horizon.horizon.TransactionCommittingError:
         """
 
         tuples = await self.tuples.tuples_with_attribute(
diff --git a/src/tgdb/entities/horizon/horizon.py b/src/tgdb/entities/horizon/horizon.py
@@ -30,7 +30,13 @@
 class NoTransactionError(Exception): ...
 
 
-class InvalidTransactionStateError(Exception): ...
+class DoubleStartTransactionError(Exception): ...
+
+
+class TransactionCommittingError(Exception): ...
+
+
+class TransactionNotCommittingError(Exception): ...
 
 
 class HorizonAlwaysWithoutTransactionsError(Exception): ...
@@ -76,12 +82,12 @@ def start_transaction(
     ) -> XID:
         """
         :raises tgdb.entities.horizon.horizon.NotMonotonicTimeError:
-        :raises tgdb.entities.horizon.horizon.InvalidTransactionStateError:
+        :raises tgdb.entities.horizon.horizon.DoubleStartTransactionError:
         """
 
         assert_(
             all(xid not in map for map in self._transaction_maps()),
-            else_=InvalidTransactionStateError,
+            else_=DoubleStartTransactionError,
         )
 
         started_transaction = start_transaction(
@@ -107,25 +113,32 @@ def include(
         """
         :raises tgdb.entities.horizon.horizon.NotMonotonicTimeError:
         :raises tgdb.entities.horizon.horizon.NoTransactionError:
-        :raises tgdb.entities.horizon.horizon.InvalidTransactionStateError:
+        :raises tgdb.entities.horizon.horizon.TransactionCommittingError:
         """
 
         self.move_to_future(time)
 
         transaction = self._transaction(
-            xid, SerializableTransactionState.active
+            xid,
+            SerializableTransactionState.active,
+            else_=TransactionCommittingError,
         )
         transaction.include(effect)
 
     def rollback_transaction(self, time: LogicTime, xid: XID) -> None:
         """
         :raises tgdb.entities.horizon.horizon.NotMonotonicTimeError:
         :raises tgdb.entities.horizon.horizon.NoTransactionError:
+        :raises tgdb.entities.horizon.horizon.TransactionCommittingError:
         """
 
         self.move_to_future(time)
 
-        transaction = self._transaction(xid)
+        transaction = self._transaction(
+            xid,
+            SerializableTransactionState.active,
+            else_=TransactionCommittingError,
+        )
         transaction.rollback()
         del self._transaction_map(transaction)[transaction.xid()]
 
@@ -138,14 +151,15 @@ def commit_transaction(
         """
         :raises tgdb.entities.horizon.horizon.NotMonotonicTimeError:
         :raises tgdb.entities.horizon.horizon.NoTransactionError:
-        :raises tgdb.entities.horizon.horizon.InvalidTransactionStateError:
+        :raises tgdb.entities.horizon.horizon.TransactionCommittingError:
         :raises tgdb.entities.horizon.transaction.ConflictError:
         """
 
         self.move_to_future(time)
 
         transaction = self._transaction(
-            xid, SerializableTransactionState.active
+            xid, SerializableTransactionState.active,
+            else_=TransactionCommittingError(),
         )
 
         for effect in effects:
@@ -165,14 +179,15 @@ def commit_transaction(
     def complete_commit(self, time: LogicTime, xid: XID) -> Commit:
         """
         :raises tgdb.entities.horizon.horizon.NoTransactionError:
-        :raises tgdb.entities.horizon.horizon.InvalidTransactionStateError:
+        :raises tgdb.entities.horizon.horizon.TransactionNotCommittingError:
         """
 
         self.move_to_future(time)
 
         transaction = self._serializable_transaction(
             xid,
             SerializableTransactionState.prepared,
+            else_=TransactionNotCommittingError,
         )
 
         commit = transaction.commit()
@@ -236,10 +251,12 @@ def _serializable_transaction(
         self,
         xid: XID,
         state: SerializableTransactionState | None = None,
+        *,
+        else_: Exception | type[Exception],
     ) -> SerializableTransaction:
         """
         :raises tgdb.entities.horizon.horizon.NoTransactionError:
-        :raises tgdb.entities.horizon.horizon.InvalidTransactionStateError:
+        :raises else_:
         """
 
         transaction = self._serializable_transaction_map.get(xid)
@@ -251,7 +268,7 @@ def _serializable_transaction(
             transaction.rollback()
             del self._serializable_transaction_map[xid]
 
-            raise InvalidTransactionStateError
+            raise else_
 
         return transaction
 
@@ -273,16 +290,18 @@ def _transaction(
         self,
         xid: XID,
         state: SerializableTransactionState | None = None,
+        *,
+        else_: Exception | type[Exception],
     ) -> Transaction:
         """
         :raises tgdb.entities.horizon.horizon.NoTransactionError:
-        :raises tgdb.entities.horizon.horizon.InvalidTransactionStateError:
+        :raises else_:
         """
 
         with suppress(NoTransactionError):
             return self._non_serializable_read_transaction(xid)
 
-        return self._serializable_transaction(xid, state)
+        return self._serializable_transaction(xid, state, else_=else_)
 
     def _transaction_maps(self) -> Iterable[Mapping[XID, Transaction]]:
         yield self._serializable_transaction_map
diff --git a/src/tgdb/infrastructure/adapters/channel.py b/src/tgdb/infrastructure/adapters/channel.py
@@ -3,8 +3,8 @@
 
 from tgdb.application.horizon.ports.channel import Channel, Notification
 from tgdb.entities.horizon.horizon import (
-    InvalidTransactionStateError,
     NoTransactionError,
+    TransactionNotCommittingError,
 )
 from tgdb.entities.horizon.transaction import XID
 from tgdb.infrastructure.async_map import AsyncMap
@@ -13,14 +13,14 @@
 @dataclass(frozen=True)
 class AsyncMapChannel(Channel):
     _async_map: AsyncMap[
-        XID, NoTransactionError | InvalidTransactionStateError | None
+        XID, NoTransactionError | TransactionNotCommittingError | None
     ]
 
     async def publish(
         self,
         ok_commit_xids: Sequence[XID],
         error_commit_map: Mapping[
-            XID, NoTransactionError | InvalidTransactionStateError
+            XID, NoTransactionError | TransactionNotCommittingError
         ],
     ) -> None:
         for ok_commit_xid in ok_commit_xids:
diff --git a/src/tgdb/infrastructure/adapters/relations.py b/src/tgdb/infrastructure/adapters/relations.py
@@ -24,7 +24,7 @@ async def relation(self, relation_number: Number) -> Relation:
             lambda it: it.number() == relation_number
         )
         if relation is None:
-            raise NoRelationError
+            raise NoRelationError(relation_number)
 
         return relation
 
diff --git a/src/tgdb/presentation/fastapi/horizon/error_handling.py b/src/tgdb/presentation/fastapi/horizon/error_handling.py
@@ -2,13 +2,13 @@
 from fastapi.responses import JSONResponse
 
 from tgdb.entities.horizon.horizon import (
-    InvalidTransactionStateError,
     NoTransactionError,
+    TransactionCommittingError,
 )
 from tgdb.entities.horizon.transaction import ConflictError
 from tgdb.presentation.fastapi.horizon.schemas.error import (
-    InvalidTransactionStateSchema,
     NoTransactionSchema,
+    TransactionCommittingSchema,
     TransactionConflictSchema,
 )
 
@@ -30,10 +30,10 @@ def _(_: object, __: object) -> Response:
             status_code=status.HTTP_404_NOT_FOUND,
         )
 
-    @app.exception_handler(InvalidTransactionStateError)
+    @app.exception_handler(TransactionCommittingError)
     def _(_: object, __: object) -> Response:
-        schema = InvalidTransactionStateSchema()
+        schema = TransactionCommittingSchema()
         return JSONResponse(
             schema.model_dump(mode="json", by_alias=True),
-            status_code=status.HTTP_404_NOT_FOUND,
+            status_code=status.HTTP_400_BAD_REQUEST,
         )
diff --git a/src/tgdb/presentation/fastapi/horizon/routes/commit_transaction.py b/src/tgdb/presentation/fastapi/horizon/routes/commit_transaction.py
@@ -10,23 +10,25 @@
 from tgdb.presentation.fastapi.common.schemas.operator import OperatorSchema
 from tgdb.presentation.fastapi.common.tags import Tag
 from tgdb.presentation.fastapi.horizon.schemas.error import (
-    InvalidTransactionStateSchema,
     NoTransactionSchema,
+    TransactionCommittingSchema,
     TransactionConflictSchema,
 )
 
 
 commit_transaction_router = APIRouter()
 
 description = """
-Write down all a transaction statements and commit it.
+Record all transaction operators and commit them.
 
-Transactions can be automatically rolled back if:
-1. They violate serializability
-2. The server crashed
-3. The server ran out of space for active transactions
+A transaction may fail to commit in the following cases:
+1. It is a serializable transaction that conflicts with another serializable transaction.
+2. The server runs out of space for active transactions and rolls back your transaction.
+3. The transaction rolled back due to timeout.
+4. The server crashes.
 
-Therefore, in case of any negative response, you should retry transactions in full, and not just send a new commit.
+If the commit fails, all changes in the transaction will not be applied.
+Therefore, for any negative response, retry the entire transaction.
 """  # noqa: E501
 
 
@@ -40,9 +42,7 @@ class CommitTransactionSchema(BaseModel):
     responses={
         status.HTTP_204_NO_CONTENT: {"content": None},
         status.HTTP_404_NOT_FOUND: {"model": NoTransactionSchema},
-        status.HTTP_400_BAD_REQUEST: {
-            "model": InvalidTransactionStateSchema
-        },
+        status.HTTP_400_BAD_REQUEST: {"model": TransactionCommittingSchema},
         status.HTTP_409_CONFLICT: {"model": TransactionConflictSchema},
     },
     summary="Commit transaction",
diff --git a/src/tgdb/presentation/fastapi/horizon/routes/rollback_transaction.py b/src/tgdb/presentation/fastapi/horizon/routes/rollback_transaction.py
@@ -5,24 +5,32 @@
 from tgdb.application.horizon.rollback_transaction import RollbackTransaction
 from tgdb.entities.horizon.transaction import XID
 from tgdb.presentation.fastapi.common.tags import Tag
-from tgdb.presentation.fastapi.horizon.schemas.error import NoTransactionSchema
+from tgdb.presentation.fastapi.horizon.schemas.error import (
+    NoTransactionSchema,
+    TransactionCommittingSchema,
+)
 
 
 rollback_transaction_router = APIRouter()
 
+description = """
+Roll back the transaction as if it had never started.
+
+If the transaction cannot be rolled back, it will be rolled back automatically
+over time.
+"""
+
 
 @rollback_transaction_router.delete(
     "/transactions/{xid}",
     status_code=status.HTTP_204_NO_CONTENT,
     responses={
         status.HTTP_204_NO_CONTENT: {"content": None},
+        status.HTTP_400_BAD_REQUEST: {"model": TransactionCommittingSchema},
         status.HTTP_404_NOT_FOUND: {"model": NoTransactionSchema},
     },
     summary="Rollback transaction",
-    description=(
-        "If you don't roll back a transaction"
-        ", it will roll back itself over time."
-    ),
+    description=description,
     tags=[Tag.transaction],
 )
 @inject
diff --git a/src/tgdb/presentation/fastapi/horizon/routes/start_transaction.py b/src/tgdb/presentation/fastapi/horizon/routes/start_transaction.py
diff --git a/src/tgdb/presentation/fastapi/horizon/schemas/error.py b/src/tgdb/presentation/fastapi/horizon/schemas/error.py
diff --git a/src/tgdb/presentation/fastapi/relation/routes/view_tuples.py b/src/tgdb/presentation/fastapi/relation/routes/view_tuples.py
diff --git a/tests/test_tgdb/test_entities/test_horizon/test_horizon.py b/tests/test_tgdb/test_entities/test_horizon/test_horizon.py

Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@ async def relation(self, relation_number: Number) -> Relation:`
`24`	`24`	`lambda it: it.number() == relation_number`
`25`	`25`	`)`
`26`	`26`	`if relation is None:`
`27`		`- raise NoRelationError`
	`27`	`+ raise NoRelationError(relation_number)`
`28`	`28`
`29`	`29`	`return relation`
`30`	`30`