feat: add NoResultError to abort retries immediately

Author: theseriff

docs/advanced_usage/exception_handlers.md

@@ -107,11 +107,43 @@ async def my_recovery_handler(exc: Exception, context: JobContext) -> str:
 @app.task(exception_handlers={ValueError: my_recovery_handler})
 async def my_task() -> None:
     raise ValueError("Oops!")
+```
+
+### 3. Aborting Retries with NoResultError
+
+Sometimes, an error can be fatal and retrying a task (even if the `retry` configuration is set) would be a waste of resources.
+In these cases, it is recommended to raise the `jobify.exceptions.NoResultError` exception.
+
+- When this exception is raised, the job's status will be set to FAILED.
+- The `RetryMiddleware` component will catch this exception and stop all further retries.
+- No more retries will be attempted.
+
+```python
+import asyncio
+
+from jobify import JobContext, Jobify
+from jobify.exceptions import NoResultError
+
+app = Jobify()
+
+async def fatal_error_handler(exc: Exception, context: JobContext) -> None:
+    print(f"Fatal error in job {context.job.id}: {exc}")
+    # Signal that we should stop retries and fail the job immediately
+    raise NoResultError
+
+@app.task(retry=3, exception_handlers={ValueError: fatal_error_handler})
+async def my_task() -> None:
+    raise ValueError("Corrupted data!")
+
+async def main() -> None:
+    async with app:
+        job = await my_task.push()
+        await job.wait()
+
+        print(job.status) # FAILED
+        print(job.exception) # NoResultError
 
-# ... after execution ...
-await job.wait()
-print(job.status) # SUCCESS
-print(job.result()) # "default_value"
+asyncio.run(main())
 ```
 
 ## Example: Hierarchical Handling

src/jobify/_internal/common/datastructures.py

@@ -11,7 +11,6 @@ class EmptyPlaceholder(str):
     __slots__: tuple[()] = ()
 
     def __new__(cls) -> Self:
-        # Создаем пустую строку как основу
         return super().__new__(cls, "__EMPTY__")
 
     def __bool__(self) -> Literal[False]:

src/jobify/_internal/exceptions.py

@@ -102,3 +102,12 @@ def raise_app_already_started_error(operation: str) -> NoReturn:
             "Move this call outside/before the 'async with jobify:' block."
         ),
     )
+
+
+class NoResultError(BaseJobifyError):
+    """Raised when a task should fail immediately without retrying."""
+
+    def __init__(
+        self, msg: str = "Job aborted: no result expected and retries stopped."
+    ) -> None:
+        super().__init__(msg)

src/jobify/_internal/middleware/retry.py

@@ -6,6 +6,7 @@
 
 from typing_extensions import override
 
+from jobify._internal.exceptions import NoResultError
 from jobify._internal.middleware.base import BaseMiddleware, CallNext
 
 if TYPE_CHECKING:
@@ -25,7 +26,9 @@ async def __call__(self, call_next: CallNext, context: JobContext) -> Any:
         while True:
             try:
                 return await call_next(context)
-            except Exception as exc:  # noqa: PERF203
+            except NoResultError:  # noqa: PERF203
+                raise
+            except Exception as exc:
                 failures += 1
                 if failures > max_retries:
                     msg = (

src/jobify/_internal/scheduler/job.py

@@ -138,8 +138,8 @@ def set_exception(self, exc: Exception, *, status: JobStatus) -> None:
         self.status = status
 
     def update(self, *, exec_at: datetime, status: JobStatus) -> None:
-        self.status = status
         self._event = asyncio.Event()
+        self.status = status
         self.exec_at = exec_at
 
     def is_done(self) -> bool:

src/jobify/exceptions/__init__.py

@@ -12,6 +12,7 @@
     JobFailedError,
     JobNotCompletedError,
     JobTimeoutError,
+    NoResultError,
     RouteAlreadyRegisteredError,
 )
 
@@ -22,5 +23,6 @@
     "JobFailedError",
     "JobNotCompletedError",
     "JobTimeoutError",
+    "NoResultError",
     "RouteAlreadyRegisteredError",
 )

tests/test_middleware.py

@@ -2,9 +2,12 @@
 from typing import Any
 from unittest.mock import AsyncMock, Mock, call, patch, sentinel
 
+import pytest
 from typing_extensions import override
 
 from jobify import JobContext, JobStatus, OuterContext
+from jobify._internal.common.constants import EMPTY
+from jobify.exceptions import JobFailedError, NoResultError
 from jobify.middleware import (
     BaseMiddleware,
     BaseOuterMiddleware,
@@ -124,3 +127,22 @@ async def __call__(
     async with app:
         job = await f.schedule().delay(0.01)
         assert job._handle is handle is not None
+
+
+async def test_retry_no_result_error(amock: AsyncMock) -> None:
+    amock.side_effect = NoResultError("Fatal failure")
+
+    app = create_app()
+    f = app.task(amock, retry=3)
+    async with app:
+        job = await f.push()
+        await job.wait()
+
+    assert job.status is JobStatus.FAILED
+
+    with pytest.raises(JobFailedError, match="Fatal failure"):
+        job.result()
+
+    assert job._result is EMPTY
+    assert type(job.exception) is NoResultError
+    amock.assert_awaited_once()