Add suspend and resume reasons

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 941fc052-b910-42af-93fa-4f00138813ab

Author: andystaples

CHANGELOG.md

@@ -7,6 +7,12 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+ADDED
+
+- Added optional `reason` parameters to `TaskHubGrpcClient` and
+`AsyncTaskHubGrpcClient` suspend and resume operations. The reason is now sent
+to the backend with the lifecycle request.
+
 ## v1.9.0
 
 ADDED

azure-functions-durable/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+FIXED
+
+- Fixed deprecated `DurableFunctionsClient.suspend()` and `resume()` methods
+discarding their `reason` arguments. Reasons are now forwarded to the Durable
+Task backend.
+
 ## v2.0.0b2
 
 ADDED

azure-functions-durable/azure/durable_functions/client.py

@@ -431,21 +431,13 @@ async def purge_instance_history(self, instance_id: str) -> PurgeHistoryResult:
 
     @deprecated("suspend is deprecated; use suspend_orchestration instead.")
     async def suspend(self, instance_id: str, reason: Optional[str] = None) -> None:
-        """Deprecated alias for :meth:`suspend_orchestration`.
-
-        The v1 ``reason`` argument has no equivalent in durabletask and is
-        ignored.
-        """
-        await self.suspend_orchestration(instance_id)
+        """Deprecated alias for :meth:`suspend_orchestration`."""
+        await self.suspend_orchestration(instance_id, reason=reason)
 
     @deprecated("resume is deprecated; use resume_orchestration instead.")
     async def resume(self, instance_id: str, reason: Optional[str] = None) -> None:
-        """Deprecated alias for :meth:`resume_orchestration`.
-
-        The v1 ``reason`` argument has no equivalent in durabletask and is
-        ignored.
-        """
-        await self.resume_orchestration(instance_id)
+        """Deprecated alias for :meth:`resume_orchestration`."""
+        await self.resume_orchestration(instance_id, reason=reason)
 
     @deprecated("restart is deprecated; use restart_orchestration instead.")
     async def restart(

durabletask/client.py

@@ -786,13 +786,21 @@ def terminate_orchestration(self, instance_id: str, *,
             )
         self._stub.TerminateInstance(req)
 
-    def suspend_orchestration(self, instance_id: str) -> None:
-        req = pb.SuspendRequest(instanceId=instance_id)
+    def suspend_orchestration(self, instance_id: str, *,
+                              reason: str | None = None) -> None:
+        req = pb.SuspendRequest(
+            instanceId=instance_id,
+            reason=helpers.get_string_value(reason),
+        )
         self._logger.info(f"Suspending instance '{instance_id}'.")
         self._stub.SuspendInstance(req)
 
-    def resume_orchestration(self, instance_id: str) -> None:
-        req = pb.ResumeRequest(instanceId=instance_id)
+    def resume_orchestration(self, instance_id: str, *,
+                             reason: str | None = None) -> None:
+        req = pb.ResumeRequest(
+            instanceId=instance_id,
+            reason=helpers.get_string_value(reason),
+        )
         self._logger.info(f"Resuming instance '{instance_id}'.")
         self._stub.ResumeInstance(req)
 
@@ -1320,13 +1328,21 @@ async def terminate_orchestration(self, instance_id: str, *,
             )
         await self._get_stub().TerminateInstance(req)
 
-    async def suspend_orchestration(self, instance_id: str) -> None:
-        req = pb.SuspendRequest(instanceId=instance_id)
+    async def suspend_orchestration(self, instance_id: str, *,
+                                    reason: str | None = None) -> None:
+        req = pb.SuspendRequest(
+            instanceId=instance_id,
+            reason=helpers.get_string_value(reason),
+        )
         self._logger.info(f"Suspending instance '{instance_id}'.")
         await self._get_stub().SuspendInstance(req)
 
-    async def resume_orchestration(self, instance_id: str) -> None:
-        req = pb.ResumeRequest(instanceId=instance_id)
+    async def resume_orchestration(self, instance_id: str, *,
+                                   reason: str | None = None) -> None:
+        req = pb.ResumeRequest(
+            instanceId=instance_id,
+            reason=helpers.get_string_value(reason),
+        )
         self._logger.info(f"Resuming instance '{instance_id}'.")
         await self._get_stub().ResumeInstance(req)
 

tests/azure-functions-durable/test_client_compat.py

@@ -472,13 +472,13 @@ async def test_suspend_resume_delegate():
                           new=AsyncMock()) as suspend_mock:
             with pytest.warns(DeprecationWarning):
                 await client.suspend("abc", "reason")
-        suspend_mock.assert_awaited_once_with("abc")
+        suspend_mock.assert_awaited_once_with("abc", reason="reason")
 
         with patch.object(client, "resume_orchestration",
                           new=AsyncMock()) as resume_mock:
             with pytest.warns(DeprecationWarning):
                 await client.resume("abc", "reason")
-        resume_mock.assert_awaited_once_with("abc")
+        resume_mock.assert_awaited_once_with("abc", reason="reason")
     finally:
         await client.close()
 

tests/durabletask/test_client.py

@@ -1258,6 +1258,43 @@ def test_worker_stores_resiliency_options():
     assert worker._resiliency_options is resiliency
 
 
+def test_suspend_resume_orchestration_include_optional_reason():
+    stub = MagicMock()
+
+    with patch('durabletask.client.shared.get_grpc_channel', return_value=MagicMock()), patch(
+            'durabletask.client.stubs.TaskHubSidecarServiceStub', return_value=stub):
+        client = TaskHubGrpcClient()
+        client.suspend_orchestration('suspended', reason='maintenance')
+        client.resume_orchestration('resumed')
+
+    suspend_request = stub.SuspendInstance.call_args.args[0]
+    assert suspend_request.instanceId == 'suspended'
+    assert suspend_request.reason.value == 'maintenance'
+    resume_request = stub.ResumeInstance.call_args.args[0]
+    assert resume_request.instanceId == 'resumed'
+    assert not resume_request.HasField('reason')
+
+
+@pytest.mark.asyncio
+async def test_async_suspend_resume_orchestration_include_optional_reason():
+    stub = MagicMock()
+    stub.SuspendInstance = AsyncMock()
+    stub.ResumeInstance = AsyncMock()
+
+    with patch('durabletask.client.shared.get_async_grpc_channel', return_value=MagicMock()), patch(
+            'durabletask.client.stubs.TaskHubSidecarServiceStub', return_value=stub):
+        client = AsyncTaskHubGrpcClient()
+        await client.suspend_orchestration('suspended')
+        await client.resume_orchestration('resumed', reason='maintenance complete')
+
+    suspend_request = stub.SuspendInstance.call_args.args[0]
+    assert suspend_request.instanceId == 'suspended'
+    assert not suspend_request.HasField('reason')
+    resume_request = stub.ResumeInstance.call_args.args[0]
+    assert resume_request.instanceId == 'resumed'
+    assert resume_request.reason.value == 'maintenance complete'
+
+
 def test_get_orchestration_history_aggregates_chunks_and_deexternalizes_payloads():
     store = FakePayloadStore()
     token = store.upload(b'history payload')