Skip to content

Commit 6cc6e43

Browse files
committed
Make workflow memo updates portable across service mode
1 parent bf96d97 commit 6cc6e43

11 files changed

Lines changed: 660 additions & 11 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88

99
The Python SDK advances to prerelease `2.0.0-rc.35`. PyPI displays the normalized
1010
PEP 440 identity `2.0.0rc35`. This Avro-only SDK release is qualified with Server
11-
`2.0.0-rc.43`; JSON remains HTTP transport and is no longer a workflow payload
11+
`2.0.0-rc.47`; JSON remains HTTP transport and is no longer a workflow payload
1212
codec.
1313
Earlier SDK versions remain historical releases and are not alternate supported
1414
2.0 baselines; no prerelease compatibility shim is provided.
1515

1616
### Added
17+
- `WorkflowContext.upsert_memo()` now authors validated memo patches, replays
18+
`MemoUpserted` identities, carries opaque payload envelopes, and fails before
19+
completion when runtime capability discovery does not advertise memo updates.
1720
- List-yield parallel composition now accepts nested activity, child-workflow,
1821
and timer groups, schedules every durable leaf through the existing command
1922
protocol, restores the nested input shape on replay, and keeps stable full

‎pyproject.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,8 +70,8 @@ durable-workflow-workflow-updates-conformance = "durable_workflow.workflow_updat
7070
[tool.durable-workflow]
7171
product-train = "2.0.0-rc.35"
7272
registry-version = "2.0.0rc35"
73-
supported-server-versions = "2.0.0-rc.43"
74-
worker-protocol-version = "1.1"
73+
supported-server-versions = "2.0.0-rc.47"
74+
worker-protocol-version = "1.14"
7575
control-plane-version = "2"
7676
workflow-streams-contract = "durable-workflow.v2.workflow-streams.contract@1"
7777
workflow-streams-operations = "list,describe,subscribe,append,close,error"

‎src/durable_workflow/client.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@
5959
from .nexus import NexusOperationResult, nexus_request_payload
6060
from .retry_policy import TransportRetryPolicy
6161

62-
PROTOCOL_VERSION = "1.1"
62+
PROTOCOL_VERSION = "1.14"
6363
CONTROL_PLANE_VERSION = "2"
6464
CONTROL_PLANE_REQUEST_CONTRACT_SCHEMA = "durable-workflow.v2.control-plane-request.contract"
6565
CONTROL_PLANE_REQUEST_CONTRACT_VERSION = 1

‎src/durable_workflow/worker.py‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@
7878
Command,
7979
NexusServiceCall,
8080
RecordSideEffect,
81+
UpsertMemo,
8182
apply_update,
8283
commands_to_server_commands,
8384
query_state,
@@ -829,6 +830,23 @@ def _server_supports_query_tasks(info: dict[str, Any]) -> bool:
829830
return isinstance(capabilities, dict) and capabilities.get("query_tasks") is True
830831

831832

833+
def _server_supports_workflow_memo_updates(info: dict[str, Any]) -> bool:
834+
worker_protocol = info.get("worker_protocol")
835+
if not isinstance(worker_protocol, dict):
836+
return False
837+
capabilities = worker_protocol.get("server_capabilities")
838+
if not isinstance(capabilities, dict):
839+
return False
840+
memo = capabilities.get("workflow_memo_updates")
841+
supported_commands = capabilities.get("supported_workflow_task_commands")
842+
return (
843+
isinstance(memo, dict)
844+
and memo.get("supported") is True
845+
and isinstance(supported_commands, list)
846+
and "upsert_memo" in supported_commands
847+
)
848+
849+
832850
def _server_supports_update_validation_tasks(info: dict[str, Any]) -> bool:
833851
worker_protocol = info.get("worker_protocol")
834852
if not isinstance(worker_protocol, dict):
@@ -952,6 +970,7 @@ def __init__(
952970
self._registration_done = asyncio.Event()
953971
self._shutdown_task: asyncio.Task[None] | None = None
954972
self._query_tasks_supported = False
973+
self._workflow_memo_updates_supported = False
955974
self._update_validation_tasks_supported = False
956975
self._query_thread_stop = threading.Event()
957976
self._query_thread: threading.Thread | None = None
@@ -1072,6 +1091,7 @@ async def _register(self) -> None:
10721091

10731092
_validate_server_compatibility(info)
10741093
self._query_tasks_supported = _server_supports_query_tasks(info)
1094+
self._workflow_memo_updates_supported = _server_supports_workflow_memo_updates(info)
10751095
has_update_validators = any(
10761096
contract["update_validators"] for contract in self.workflow_command_contracts.values()
10771097
)
@@ -1443,6 +1463,26 @@ async def _run_workflow_task_core(self, task: dict[str, Any]) -> list[dict[str,
14431463
log.warning("failed to report workflow Nexus resolution failure: %s", fe)
14441464
return None
14451465

1466+
if (
1467+
any(isinstance(command, UpsertMemo) for command in workflow_commands)
1468+
and not self._workflow_memo_updates_supported
1469+
):
1470+
message = (
1471+
"workflow_memo_updates_unavailable: the connected runtime did not advertise "
1472+
"workflow memo update support"
1473+
)
1474+
try:
1475+
await self.client.fail_workflow_task(
1476+
task_id=task_id,
1477+
lease_owner=self.worker_id,
1478+
workflow_task_attempt=attempt,
1479+
message=message,
1480+
failure_type="RuntimeCapabilityUnsupported",
1481+
)
1482+
except Exception as failure_error:
1483+
log.warning("failed to report workflow memo capability failure: %s", failure_error)
1484+
return None
1485+
14461486
commands = commands_to_server_commands(
14471487
workflow_commands,
14481488
self.task_queue,

‎src/durable_workflow/workflow.py‎

Lines changed: 184 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,13 @@
1818

1919
from __future__ import annotations
2020

21+
import base64
2122
import contextlib
2223
import hashlib
2324
import logging
2425
import math
2526
import random
27+
import re
2628
import uuid
2729
from collections.abc import Callable, Iterable, Mapping, Sequence
2830
from copy import copy
@@ -965,6 +967,96 @@ def to_server_command(
965967
}
966968

967969

970+
_MEMO_KEY_PATTERN = re.compile(r"^(?!-?[0-9]+$)[A-Za-z0-9_.:-]{1,64}$")
971+
_MAX_MEMO_ENTRIES = 100
972+
_MAX_MEMO_VALUE_SIZE_BYTES = 10_240
973+
_MAX_MEMO_TOTAL_SIZE_BYTES = 65_536
974+
975+
976+
def _canonical_memo_value(value: Any) -> Any:
977+
value = serializer.to_avro_payload_value(value)
978+
if isinstance(value, Mapping):
979+
normalized: dict[str, Any] = {}
980+
for key, nested in value.items():
981+
if not isinstance(key, str):
982+
raise ValueError("workflow memo map keys must be strings")
983+
normalized[key] = _canonical_memo_value(nested)
984+
return {key: normalized[key] for key in sorted(normalized)}
985+
if isinstance(value, list):
986+
return [_canonical_memo_value(item) for item in value]
987+
serializer.encode(value, size_warning=None)
988+
return value
989+
990+
991+
def _memo_avro_bytes(value: Any) -> bytes:
992+
return base64.b64decode(serializer.encode(value, size_warning=None), validate=True)
993+
994+
995+
def _memo_replay_identity(value: Mapping[str, Any]) -> str:
996+
return serializer.encode(_canonical_memo_entries(value), size_warning=None)
997+
998+
999+
def _canonical_memo_entries(entries: Mapping[str, Any], *, require_entries: bool = True) -> dict[str, Any]:
1000+
if require_entries and not entries:
1001+
raise ValueError("workflow memo updates require at least one entry")
1002+
if len(entries) > _MAX_MEMO_ENTRIES:
1003+
raise ValueError(f"workflow memo updates may contain at most {_MAX_MEMO_ENTRIES} entries")
1004+
1005+
normalized: dict[str, Any] = {}
1006+
for key, value in entries.items():
1007+
if not isinstance(key, str) or _MEMO_KEY_PATTERN.fullmatch(key) is None:
1008+
raise ValueError("workflow memo keys must match ^(?!-?[0-9]+$)[A-Za-z0-9_.:-]{1,64}$")
1009+
canonical = _canonical_memo_value(value)
1010+
if len(_memo_avro_bytes(canonical)) > _MAX_MEMO_VALUE_SIZE_BYTES:
1011+
raise ValueError(
1012+
f"workflow memo value {key!r} exceeds the {_MAX_MEMO_VALUE_SIZE_BYTES}-byte limit"
1013+
)
1014+
normalized[key] = canonical
1015+
1016+
normalized = {key: normalized[key] for key in sorted(normalized)}
1017+
if len(_memo_avro_bytes(normalized)) > _MAX_MEMO_TOTAL_SIZE_BYTES:
1018+
raise ValueError(
1019+
f"workflow memo update exceeds the {_MAX_MEMO_TOTAL_SIZE_BYTES}-byte total limit"
1020+
)
1021+
return normalized
1022+
1023+
1024+
@dataclass
1025+
class UpsertMemo:
1026+
"""Merge non-indexed workflow memo metadata through durable history.
1027+
1028+
``None`` deletes a key. The SDK encodes the complete patch in the public
1029+
Avro payload envelope consumed by Server and Cloud runtimes.
1030+
"""
1031+
1032+
entries: dict[str, Any]
1033+
1034+
def __post_init__(self) -> None:
1035+
self.entries = _canonical_memo_entries(self.entries)
1036+
1037+
def to_server_command(
1038+
self,
1039+
task_queue: str,
1040+
*,
1041+
payload_codec: str = serializer.AVRO_CODEC,
1042+
size_warning: serializer.PayloadSizeWarningConfig | None = serializer.DEFAULT_PAYLOAD_SIZE_WARNING,
1043+
warning_context: PayloadWarningContext = None,
1044+
) -> dict[str, Any]:
1045+
return {
1046+
"type": "upsert_memo",
1047+
"entries": serializer.envelope(
1048+
self.entries,
1049+
codec=payload_codec,
1050+
size_warning=size_warning,
1051+
warning_context=_payload_warning_context(
1052+
warning_context,
1053+
kind="workflow_memo_entries",
1054+
task_queue=task_queue,
1055+
),
1056+
),
1057+
}
1058+
1059+
9681060
@dataclass
9691061
class WaitCondition:
9701062
"""Command that yields execution until a workflow-defined predicate becomes true.
@@ -1026,7 +1118,7 @@ def _condition_predicate_fingerprint(predicate: Callable[[], bool]) -> str:
10261118
Command = (
10271119
ScheduleActivity | StartTimer | CompleteWorkflow | FailWorkflow
10281120
| CompleteUpdate | FailUpdate | ContinueAsNew | RecordSideEffect | StartChildWorkflow
1029-
| NexusServiceCall | RecordVersionMarker | UpsertSearchAttributes | WaitCondition
1121+
| NexusServiceCall | RecordVersionMarker | UpsertMemo | UpsertSearchAttributes | WaitCondition
10301122
)
10311123

10321124

@@ -1705,6 +1797,10 @@ def deprecate_patch(self, change_id: str) -> RecordVersionMarker:
17051797
def upsert_search_attributes(self, attributes: dict[str, Any]) -> UpsertSearchAttributes:
17061798
return UpsertSearchAttributes(attributes=dict(attributes))
17071799

1800+
def upsert_memo(self, entries: Mapping[str, Any]) -> UpsertMemo:
1801+
"""Return a replayable memo merge command with structural validation."""
1802+
return UpsertMemo(entries=dict(entries))
1803+
17081804
def continue_as_new(
17091805
self,
17101806
*args: Any,
@@ -2770,6 +2866,11 @@ def _recorded_step_details(payload: Mapping[str, Any]) -> dict[str, Any]:
27702866
value = payload.get(key)
27712867
if isinstance(value, str) and value:
27722868
details[key] = value
2869+
entries = payload.get("entries")
2870+
if isinstance(entries, Mapping):
2871+
details["entries_identity"] = _memo_replay_identity(
2872+
_decode_memo_history_map(entries, require_entries=True)
2873+
)
27732874
raw_parallel_path = payload.get("parallel_group_path")
27742875
if (
27752876
isinstance(raw_parallel_path, list)
@@ -2793,6 +2894,20 @@ def _recorded_step_details(payload: Mapping[str, Any]) -> dict[str, Any]:
27932894
return details
27942895

27952896

2897+
def _decode_memo_history_map(
2898+
envelope: Mapping[str, Any],
2899+
*,
2900+
require_entries: bool,
2901+
) -> dict[str, Any]:
2902+
"""Decode the inline Avro map envelope persisted in MemoUpserted history."""
2903+
if set(envelope) != {"codec", "blob"}:
2904+
raise ValueError("MemoUpserted history requires exactly the public {codec, blob} payload envelope")
2905+
decoded = serializer.decode_envelope(dict(envelope))
2906+
if not isinstance(decoded, Mapping):
2907+
raise ValueError("MemoUpserted Avro payload must decode to a string-keyed map")
2908+
return _canonical_memo_entries(decoded, require_entries=require_entries)
2909+
2910+
27962911
def _is_resolved_step_event(
27972912
event_type: str | None,
27982913
payload: Mapping[str, Any],
@@ -2808,6 +2923,7 @@ def _is_resolved_step_event(
28082923
"ChildRunTerminated",
28092924
"SideEffectRecorded",
28102925
"VersionMarkerRecorded",
2926+
"MemoUpserted",
28112927
"SearchAttributesUpserted",
28122928
):
28132929
return True
@@ -2829,6 +2945,8 @@ def _command_history_shape(command: Any) -> str | None:
28292945
return "side effect"
28302946
if isinstance(command, RecordVersionMarker):
28312947
return "version marker"
2948+
if isinstance(command, UpsertMemo):
2949+
return "memo upsert"
28322950
if isinstance(command, UpsertSearchAttributes):
28332951
return "search attributes upsert"
28342952
if isinstance(command, WaitCondition):
@@ -2882,6 +3000,10 @@ def _recorded_detail_mismatch(command: Any, step: _RecordedStep) -> str | None:
28823000
f"Recorded version change_id {recorded!r}, but current workflow "
28833001
f"requested {command.change_id!r}."
28843002
)
3003+
elif isinstance(command, UpsertMemo):
3004+
recorded = step.details.get("entries_identity")
3005+
if isinstance(recorded, str) and recorded != _memo_replay_identity(command.entries):
3006+
return "Recorded memo entries differ from the current workflow memo update."
28853007
return None
28863008

28873009

@@ -3047,7 +3169,13 @@ def _replay_state(
30473169
continue
30483170
if event_type is not None:
30493171
event_types_by_sequence.setdefault(sequence, []).append(event_type)
3050-
details_by_sequence.setdefault(sequence, {}).update(_recorded_step_details(payload))
3172+
try:
3173+
recorded_details = _recorded_step_details(payload)
3174+
except (TypeError, ValueError):
3175+
# The sequence-specific history parser below turns malformed memo
3176+
# envelopes into the public non-determinism diagnostic.
3177+
recorded_details = {}
3178+
details_by_sequence.setdefault(sequence, {}).update(recorded_details)
30513179
if event_type == "ConditionWaitOpened":
30523180
wait_id = payload.get("condition_wait_id")
30533181
if isinstance(wait_id, str) and wait_id:
@@ -3102,6 +3230,7 @@ def _state(commands: list[Command]) -> _ReplayState:
31023230
recorded_wait_steps: list[_RecordedStep] = []
31033231
recorded_pending_steps: list[_RecordedStep] = []
31043232
pending_sequences_added: set[int] = set()
3233+
memo_sequences_added: set[int] = set()
31053234
# External receivers normally apply by resolved-result cursor. Receivers
31063235
# observed while a condition wait is open are pinned to that wait so
31073236
# sequential signal-driven waits do not collapse to the same cursor.
@@ -3461,6 +3590,58 @@ def _receiver_condition_wait_bindings() -> dict[int, str | None]:
34613590
_append_pending_step("child workflow", ev)
34623591
elif etype == "VersionMarkerRecorded":
34633592
_append_resolved_result(payload.get("version", 0), "version marker", ev)
3593+
elif etype == "MemoUpserted":
3594+
sequence = _workflow_sequence(payload)
3595+
if sequence is None:
3596+
raise NonDeterministicReplayError(
3597+
len(recorded_steps) + 1,
3598+
"memo upsert with positive workflow sequence",
3599+
["MemoUpserted"],
3600+
detail="MemoUpserted history must retain its replay sequence.",
3601+
)
3602+
if sequence in memo_sequences_added:
3603+
raise NonDeterministicReplayError(
3604+
sequence,
3605+
"one MemoUpserted event",
3606+
["MemoUpserted", "MemoUpserted"],
3607+
detail="A workflow sequence cannot record the same memo update twice.",
3608+
)
3609+
entries = payload.get("entries")
3610+
if not isinstance(entries, Mapping):
3611+
raise NonDeterministicReplayError(
3612+
sequence,
3613+
"memo upsert with canonical entries",
3614+
["MemoUpserted"],
3615+
detail="MemoUpserted history must retain the applied entries as replay identity.",
3616+
)
3617+
try:
3618+
_decode_memo_history_map(entries, require_entries=True)
3619+
except (TypeError, ValueError) as exc:
3620+
raise NonDeterministicReplayError(
3621+
sequence,
3622+
"memo upsert with canonical Avro entries envelope",
3623+
["MemoUpserted"],
3624+
detail=f"MemoUpserted history has invalid entries: {exc}",
3625+
) from exc
3626+
merged = payload.get("merged")
3627+
if not isinstance(merged, Mapping):
3628+
raise NonDeterministicReplayError(
3629+
sequence,
3630+
"memo upsert with merged projection",
3631+
["MemoUpserted"],
3632+
detail="MemoUpserted history must retain the merged memo projection.",
3633+
)
3634+
try:
3635+
_decode_memo_history_map(merged, require_entries=False)
3636+
except (TypeError, ValueError) as exc:
3637+
raise NonDeterministicReplayError(
3638+
sequence,
3639+
"memo upsert with merged Avro projection envelope",
3640+
["MemoUpserted"],
3641+
detail=f"MemoUpserted history has invalid merged projection: {exc}",
3642+
) from exc
3643+
memo_sequences_added.add(sequence)
3644+
_append_resolved_result(None, "memo upsert", ev)
34643645
elif etype == "SearchAttributesUpserted":
34653646
_append_resolved_result(None, "search attributes upsert", ev)
34663647
elif etype == "SignalReceived":
@@ -3837,7 +4018,7 @@ def _terminal_state(value: Any, *, include_pending: bool) -> _ReplayState:
38374018
pending.append(cmd)
38384019
next_value = cmd.result
38394020
continue
3840-
if isinstance(cmd, UpsertSearchAttributes):
4021+
if isinstance(cmd, UpsertMemo | UpsertSearchAttributes):
38414022
if result_cursor < len(resolved_results):
38424023
_assert_next_step_matches(cmd)
38434024
next_value = resolved_results[result_cursor]

0 commit comments

Comments
 (0)