|
61 | 61 |
|
62 | 62 | PROTOCOL_VERSION = "1.16" |
63 | 63 | CONTROL_PLANE_VERSION = "2" |
| 64 | +_MESSAGE_STREAMS_CAPABILITY = "message_streams" |
| 65 | +_MESSAGE_STREAMS_MINIMUM_WORKER_PROTOCOL = (1, 15) |
64 | 66 | CONTROL_PLANE_REQUEST_CONTRACT_SCHEMA = "durable-workflow.v2.control-plane-request.contract" |
65 | 67 | CONTROL_PLANE_REQUEST_CONTRACT_VERSION = 1 |
66 | 68 | _QUERY_TASKS_DISCOVERY_PATH = "worker_protocol.server_capabilities.query_tasks" |
@@ -128,6 +130,18 @@ def _protocol_version_from_env(name: str, default: str) -> str: |
128 | 130 | return value.strip() |
129 | 131 |
|
130 | 132 |
|
| 133 | +def _worker_protocol_supports_message_streams() -> bool: |
| 134 | + version = _protocol_version_from_env( |
| 135 | + "DURABLE_WORKFLOW_WORKER_PROTOCOL_VERSION", |
| 136 | + PROTOCOL_VERSION, |
| 137 | + ) |
| 138 | + parts = version.split(".") |
| 139 | + if len(parts) != 2 or not all(part.isdigit() for part in parts): |
| 140 | + return False |
| 141 | + |
| 142 | + return (int(parts[0]), int(parts[1])) >= _MESSAGE_STREAMS_MINIMUM_WORKER_PROTOCOL |
| 143 | + |
| 144 | + |
131 | 145 | def _normalize_base_url(base_url: str) -> str: |
132 | 146 | parsed = urlsplit(base_url) |
133 | 147 | if parsed.query or parsed.fragment: |
@@ -1240,6 +1254,20 @@ async def signal(self, signal_name: str, args: list[Any] | None = None) -> None: |
1240 | 1254 | """Deliver an external signal to this workflow. See :meth:`Client.signal_workflow`.""" |
1241 | 1255 | await self._client.signal_workflow(self.workflow_id, signal_name, args=args) |
1242 | 1256 |
|
| 1257 | + async def append_message( |
| 1258 | + self, |
| 1259 | + stream_name: str, |
| 1260 | + message_id: str, |
| 1261 | + args: list[Any] | None = None, |
| 1262 | + ) -> dict[str, Any]: |
| 1263 | + """Append one idempotently identified message to a durable input stream.""" |
| 1264 | + return await self._client.append_message_stream( |
| 1265 | + self.workflow_id, |
| 1266 | + stream_name, |
| 1267 | + message_id, |
| 1268 | + args=args, |
| 1269 | + ) |
| 1270 | + |
1243 | 1271 | async def query(self, query_name: str, args: list[Any] | None = None) -> Any: |
1244 | 1272 | """Execute a read-only query against this workflow. See :meth:`Client.query_workflow`.""" |
1245 | 1273 | return await self._client.query_workflow(self.workflow_id, query_name, args=args) |
@@ -3955,6 +3983,30 @@ async def signal_workflow( |
3955 | 3983 | ) |
3956 | 3984 | await self._request("POST", f"/workflows/{workflow_id}/signal/{signal_name}", json=body, context=workflow_id) |
3957 | 3985 |
|
| 3986 | + async def append_message_stream( |
| 3987 | + self, |
| 3988 | + workflow_id: str, |
| 3989 | + stream_name: str, |
| 3990 | + message_id: str, |
| 3991 | + *, |
| 3992 | + args: list[Any] | None = None, |
| 3993 | + ) -> dict[str, Any]: |
| 3994 | + """Append repeated input without requiring workflow-authored cursor bookkeeping.""" |
| 3995 | + body: dict[str, Any] = {"message_id": message_id} |
| 3996 | + if args is not None: |
| 3997 | + body["input"] = self._payload_envelope( |
| 3998 | + args, |
| 3999 | + kind="message_stream", |
| 4000 | + workflow_id=workflow_id, |
| 4001 | + ) |
| 4002 | + result = await self._request( |
| 4003 | + "POST", |
| 4004 | + f"/workflows/{quote(workflow_id, safe='._:-')}/message-streams/{quote(stream_name, safe='._:-')}/messages", |
| 4005 | + json=body, |
| 4006 | + context=workflow_id, |
| 4007 | + ) |
| 4008 | + return dict(result) |
| 4009 | + |
3958 | 4010 | async def query_workflow( |
3959 | 4011 | self, workflow_id: str, query_name: str, *, args: list[Any] | None = None |
3960 | 4012 | ) -> Any: |
@@ -4532,6 +4584,12 @@ async def register_worker( |
4532 | 4584 | raise ValueError("max_concurrent_workflow_tasks must be at least 1") |
4533 | 4585 | if max_concurrent_activity_tasks is not None and max_concurrent_activity_tasks < 1: |
4534 | 4586 | raise ValueError("max_concurrent_activity_tasks must be at least 1") |
| 4587 | + if ( |
| 4588 | + capabilities |
| 4589 | + and _MESSAGE_STREAMS_CAPABILITY in capabilities |
| 4590 | + and not _worker_protocol_supports_message_streams() |
| 4591 | + ): |
| 4592 | + raise ValueError("message streams require worker protocol 1.15 or newer") |
4535 | 4593 |
|
4536 | 4594 | body: dict[str, Any] = { |
4537 | 4595 | "worker_id": worker_id, |
@@ -4745,18 +4803,27 @@ async def complete_workflow_task( |
4745 | 4803 | lease_owner: str, |
4746 | 4804 | workflow_task_attempt: int, |
4747 | 4805 | commands: list[dict[str, Any]], |
| 4806 | + message_stream_cursors: list[dict[str, Any]] | None = None, |
| 4807 | + message_stream_waits: list[dict[str, Any]] | None = None, |
4748 | 4808 | ) -> Any: |
4749 | 4809 | """Report successful execution of a workflow task with its emitted commands. |
4750 | 4810 |
|
4751 | 4811 | Worker-plane endpoint, called by :class:`~durable_workflow.Worker`. |
4752 | 4812 | ``commands`` is the list of serialized commands the workflow yielded |
4753 | 4813 | for this task. |
4754 | 4814 | """ |
| 4815 | + if (message_stream_cursors or message_stream_waits) and not _worker_protocol_supports_message_streams(): |
| 4816 | + raise ValueError("message stream completion metadata requires worker protocol 1.15 or newer") |
| 4817 | + |
4755 | 4818 | body: dict[str, Any] = { |
4756 | 4819 | "lease_owner": lease_owner, |
4757 | 4820 | "workflow_task_attempt": workflow_task_attempt, |
4758 | 4821 | "commands": commands, |
4759 | 4822 | } |
| 4823 | + if message_stream_cursors: |
| 4824 | + body["message_stream_cursors"] = message_stream_cursors |
| 4825 | + if message_stream_waits: |
| 4826 | + body["message_stream_waits"] = message_stream_waits |
4760 | 4827 | return await self._request( |
4761 | 4828 | "POST", f"/worker/workflow-tasks/{task_id}/complete", worker=True, json=body |
4762 | 4829 | ) |
|
0 commit comments