added new on_cancelled event for deferred tasks

Author: Andrei Neagu

packages/service-library/src/servicelib/deferred_tasks/__init__.py

@@ -22,14 +22,16 @@
 - `cancel`: (called by the user) [optional]:
     send a message to cancel the current task. A warning will be logged but no call to either
     `on_result` or `on_finished_with_error` will occur.
+-  `on_cancelled` (called by state `ManuallyCancelled`) [optional] {can be overwritten by the user}:
+    called after the cancellation is handled by the worker executing the `run`
 
 
 ## DeferredHandler lifecycle
 
 ```mermaid
 stateDiagram-v2
-    * --> Scheduled: via [start]
-    ** --> ManuallyCancelled: via [cancel]
+    (1) --> Scheduled: via [start]
+    (2) --> ManuallyCancelled: via [cancel]
 
     ManuallyCancelled --> Worker: attempts to cancel task in
 
@@ -41,9 +43,10 @@
     ErrorResult --> FinishedWithError: gives up when out of retries or if cancelled
     Worker --> DeferredResult: success
 
-    DeferredResult --> °: calls [on_result]
-    FinishedWithError --> °°: calls [on_finished_with_error]
-    Worker --> °°°: task cancelled
+    DeferredResult --> (3): calls [on_result]
+    FinishedWithError --> (4): calls [on_finished_with_error]
+    Worker --> Removed*: task cancelled
+    Removed* --> (5): calls [on_cancelled]
 ```
 
 ### States
@@ -57,6 +60,7 @@
 - `FinishedWIthError`: logs error, invokes `on_finished_with_error` and removes the schedule
 - `DeferredResult`: invokes `on_result` and removes the schedule
 - `ManuallyCancelled`: sends message to all instances to cancel. The instance handling the task will cancel the task and remove the schedule
+- `Removed*`: is a fake state that does not exist only used to convey the information that the cancellation event is triggered after removal
 """
 
 from ._base_deferred_handler import (

packages/service-library/src/servicelib/deferred_tasks/_base_deferred_handler.py

@@ -95,6 +95,11 @@ async def on_finished_with_error(
         NOTE: by design the default action is to do nothing
         """
 
+    @classmethod
+    @abstractmethod
+    async def on_cancelled(cls, context: DeferredContext) -> None:
+        """called after handling ``cancel`` request by the copy executing ``run``"""
+
     @classmethod
     async def cancel(cls, task_uid: TaskUID) -> None:
         """cancels a deferred"""

packages/service-library/src/servicelib/deferred_tasks/_deferred_manager.py

@@ -579,6 +579,11 @@ async def _fs_handle_manually_cancelled(  # pylint:disable=method-hidden
         _logger.info("Found and cancelled run for '%s'", task_uid)
         await self.__remove_task(task_uid, task_schedule)
 
+        subclass = self.__get_subclass(task_schedule.class_unique_reference)
+        deferred_context = self.__get_deferred_context(task_schedule.start_context)
+        with log_catch(_logger, reraise=False):
+            await subclass.on_cancelled(deferred_context)
+
     async def __is_present(self, task_uid: TaskUID) -> bool:
         task_schedule: TaskScheduleModel | None = await self._task_tracker.get(task_uid)
         return task_schedule is not None

packages/service-library/tests/deferred_tasks/test__base_deferred_handler.py

@@ -46,6 +46,7 @@ class MockKeys(StrAutoEnum):
     RUN_DEFERRED_AFTER_HANDLER = auto()
     ON_DEFERRED_RESULT = auto()
     ON_FINISHED_WITH_ERROR = auto()
+    ON_CANCELLED = auto()
 
 
 @pytest.fixture
@@ -132,6 +133,10 @@ async def run(cls, context: DeferredContext) -> Any:
             async def on_result(cls, result: Any, context: DeferredContext) -> None:
                 mocks[MockKeys.ON_DEFERRED_RESULT](result, context)
 
+            @classmethod
+            async def on_cancelled(cls, context: DeferredContext) -> None:
+                mocks[MockKeys.ON_CANCELLED](context)
+
             @classmethod
             async def on_finished_with_error(
                 cls, error: TaskResultError, context: DeferredContext
@@ -324,6 +329,7 @@ async def _run_to_cancel(_: DeferredContext) -> None:
     await _assert_mock_call(mocks, key=MockKeys.RUN_DEFERRED_BEFORE_HANDLER, count=1)
     await mocked_deferred_handler.cancel(task_uid)
 
+    await _assert_mock_call(mocks, key=MockKeys.ON_CANCELLED, count=1)
     await _assert_mock_call(mocks, key=MockKeys.ON_FINISHED_WITH_ERROR, count=0)
 
     assert (