|
| 1 | +""" |
| 2 | +Copyright 2025 The Dapr Authors |
| 3 | +Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | +you may not use this file except in compliance with the License. |
| 5 | +You may obtain a copy of the License at |
| 6 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 7 | +Unless required by applicable law or agreed to in writing, software |
| 8 | +distributed under the License is distributed on an "AS IS" BASIS, |
| 9 | +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 10 | +See the License for the specific language governing permissions and |
| 11 | +limitations under the License. |
| 12 | +""" |
| 13 | + |
| 14 | +""" |
| 15 | +Deterministic utilities for Durable Task workflows (async and generator). |
| 16 | +
|
| 17 | +This module provides deterministic alternatives to non-deterministic Python |
| 18 | +functions, ensuring workflow replay consistency across different executions. |
| 19 | +It is shared by both the asyncio authoring model and the generator-based model. |
| 20 | +""" |
| 21 | + |
| 22 | +import hashlib |
| 23 | +import random |
| 24 | +import string as _string |
| 25 | +import uuid |
| 26 | +from collections.abc import Sequence |
| 27 | +from dataclasses import dataclass |
| 28 | +from datetime import datetime |
| 29 | +from typing import Optional, Protocol, TypeVar, runtime_checkable |
| 30 | + |
| 31 | + |
| 32 | +@dataclass |
| 33 | +class DeterminismSeed: |
| 34 | + """Seed data for deterministic operations.""" |
| 35 | + |
| 36 | + instance_id: str |
| 37 | + orchestration_unix_ts: int |
| 38 | + |
| 39 | + def to_int(self) -> int: |
| 40 | + """Convert seed to integer for PRNG initialization.""" |
| 41 | + combined = f"{self.instance_id}:{self.orchestration_unix_ts}" |
| 42 | + hash_bytes = hashlib.sha256(combined.encode("utf-8")).digest() |
| 43 | + return int.from_bytes(hash_bytes[:8], byteorder="big") |
| 44 | + |
| 45 | + |
| 46 | +def derive_seed(instance_id: str, orchestration_time: datetime) -> int: |
| 47 | + """ |
| 48 | + Derive a deterministic seed from instance ID and orchestration time. |
| 49 | + """ |
| 50 | + ts = int(orchestration_time.timestamp()) |
| 51 | + return DeterminismSeed(instance_id=instance_id, orchestration_unix_ts=ts).to_int() |
| 52 | + |
| 53 | + |
| 54 | +def deterministic_random(instance_id: str, orchestration_time: datetime) -> random.Random: |
| 55 | + """ |
| 56 | + Create a deterministic random number generator. |
| 57 | + """ |
| 58 | + seed = derive_seed(instance_id, orchestration_time) |
| 59 | + return random.Random(seed) |
| 60 | + |
| 61 | + |
| 62 | +def deterministic_uuid4(rnd: random.Random) -> uuid.UUID: |
| 63 | + """ |
| 64 | + Generate a deterministic UUID4 using the provided random generator. |
| 65 | +
|
| 66 | + Note: This is deprecated in favor of deterministic_uuid_v5 which matches |
| 67 | + the .NET implementation for cross-language compatibility. |
| 68 | + """ |
| 69 | + bytes_ = bytes(rnd.randrange(0, 256) for _ in range(16)) |
| 70 | + bytes_list = list(bytes_) |
| 71 | + bytes_list[6] = (bytes_list[6] & 0x0F) | 0x40 # Version 4 |
| 72 | + bytes_list[8] = (bytes_list[8] & 0x3F) | 0x80 # Variant bits |
| 73 | + return uuid.UUID(bytes=bytes(bytes_list)) |
| 74 | + |
| 75 | + |
| 76 | +def deterministic_uuid_v5(instance_id: str, current_datetime: datetime, counter: int) -> uuid.UUID: |
| 77 | + """ |
| 78 | + Generate a deterministic UUID v5 matching the .NET implementation. |
| 79 | +
|
| 80 | + This implementation matches the durabletask-dotnet NewGuid() method: |
| 81 | + https://github.com/microsoft/durabletask-dotnet/blob/main/src/Worker/Core/Shims/TaskOrchestrationContextWrapper.cs |
| 82 | +
|
| 83 | + Args: |
| 84 | + instance_id: The orchestration instance ID. |
| 85 | + current_datetime: The current orchestration datetime (frozen during replay). |
| 86 | + counter: The per-call counter (starts at 0 on each replay). |
| 87 | +
|
| 88 | + Returns: |
| 89 | + A deterministic UUID v5 that will be the same across replays. |
| 90 | + """ |
| 91 | + # DNS namespace UUID - same as .NET DnsNamespaceValue |
| 92 | + namespace = uuid.UUID("9e952958-5e33-4daf-827f-2fa12937b875") |
| 93 | + |
| 94 | + # Build name matching .NET format: instanceId_datetime_counter |
| 95 | + # Using isoformat() which produces ISO 8601 format similar to .NET's ToString("o") |
| 96 | + name = f"{instance_id}_{current_datetime.isoformat()}_{counter}" |
| 97 | + |
| 98 | + # Generate UUID v5 (SHA-1 based, matching .NET) |
| 99 | + return uuid.uuid5(namespace, name) |
| 100 | + |
| 101 | + |
| 102 | +@runtime_checkable |
| 103 | +class DeterministicContextProtocol(Protocol): |
| 104 | + """Protocol for contexts that provide deterministic operations.""" |
| 105 | + |
| 106 | + @property |
| 107 | + def instance_id(self) -> str: ... |
| 108 | + |
| 109 | + @property |
| 110 | + def current_utc_datetime(self) -> datetime: ... |
| 111 | + |
| 112 | + |
| 113 | +class DeterministicContextMixin: |
| 114 | + """ |
| 115 | + Mixin providing deterministic helpers for workflow contexts. |
| 116 | +
|
| 117 | + Assumes the inheriting class exposes `instance_id` and `current_utc_datetime` attributes. |
| 118 | +
|
| 119 | + This implementation matches the .NET durabletask SDK approach with an explicit |
| 120 | + counter for UUID generation that resets on each replay. |
| 121 | + """ |
| 122 | + |
| 123 | + def __init__(self, *args, **kwargs): |
| 124 | + """Initialize the mixin with a UUID counter.""" |
| 125 | + super().__init__(*args, **kwargs) |
| 126 | + # Counter for deterministic UUID generation (matches .NET newGuidCounter) |
| 127 | + # This counter resets to 0 on each replay, ensuring determinism |
| 128 | + self._uuid_counter: int = 0 |
| 129 | + |
| 130 | + def now(self) -> datetime: |
| 131 | + """Return orchestration time (deterministic UTC).""" |
| 132 | + value = self.current_utc_datetime # type: ignore[attr-defined] |
| 133 | + assert isinstance(value, datetime) |
| 134 | + return value |
| 135 | + |
| 136 | + def random(self) -> random.Random: |
| 137 | + """Return a PRNG seeded deterministically from instance id and orchestration time.""" |
| 138 | + rnd = deterministic_random( |
| 139 | + self.instance_id, # type: ignore[attr-defined] |
| 140 | + self.current_utc_datetime, # type: ignore[attr-defined] |
| 141 | + ) |
| 142 | + # Mark as deterministic for sandbox detector whitelisting of bound methods |
| 143 | + try: |
| 144 | + rnd._dt_deterministic = True |
| 145 | + except Exception: |
| 146 | + pass |
| 147 | + return rnd |
| 148 | + |
| 149 | + def uuid4(self) -> uuid.UUID: |
| 150 | + """ |
| 151 | + Return a deterministically generated UUID v5 with explicit counter. |
| 152 | + https://www.sohamkamani.com/uuid-versions-explained/#v5-non-random-uuids |
| 153 | +
|
| 154 | + This matches the .NET implementation's NewGuid() method which uses: |
| 155 | + - Instance ID |
| 156 | + - Current UTC datetime (frozen during replay) |
| 157 | + - Per-call counter (resets to 0 on each replay) |
| 158 | +
|
| 159 | + The counter ensures multiple calls produce different UUIDs while maintaining |
| 160 | + determinism across replays. |
| 161 | + """ |
| 162 | + # Lazily initialize counter if not set by __init__ (for compatibility) |
| 163 | + if not hasattr(self, "_uuid_counter"): |
| 164 | + self._uuid_counter = 0 |
| 165 | + |
| 166 | + result = deterministic_uuid_v5( |
| 167 | + self.instance_id, # type: ignore[attr-defined] |
| 168 | + self.current_utc_datetime, # type: ignore[attr-defined] |
| 169 | + self._uuid_counter, |
| 170 | + ) |
| 171 | + self._uuid_counter += 1 |
| 172 | + return result |
| 173 | + |
| 174 | + def new_guid(self) -> uuid.UUID: |
| 175 | + """Alias for uuid4 for API parity with other SDKs.""" |
| 176 | + return self.uuid4() |
| 177 | + |
| 178 | + def random_string(self, length: int, *, alphabet: Optional[str] = None) -> str: |
| 179 | + """Return a deterministically generated random string of the given length.""" |
| 180 | + if length < 0: |
| 181 | + raise ValueError("length must be non-negative") |
| 182 | + chars = alphabet if alphabet is not None else (_string.ascii_letters + _string.digits) |
| 183 | + if not chars: |
| 184 | + raise ValueError("alphabet must not be empty") |
| 185 | + rnd = self.random() |
| 186 | + size = len(chars) |
| 187 | + return "".join(chars[rnd.randrange(0, size)] for _ in range(length)) |
| 188 | + |
| 189 | + def random_int(self, min_value: int = 0, max_value: int = 2**31 - 1) -> int: |
| 190 | + """Return a deterministic random integer in the specified range.""" |
| 191 | + if min_value > max_value: |
| 192 | + raise ValueError("min_value must be <= max_value") |
| 193 | + rnd = self.random() |
| 194 | + return rnd.randint(min_value, max_value) |
| 195 | + |
| 196 | + T = TypeVar("T") |
| 197 | + |
| 198 | + def random_choice(self, sequence: Sequence[T]) -> T: |
| 199 | + """Return a deterministic random element from a non-empty sequence.""" |
| 200 | + if not sequence: |
| 201 | + raise IndexError("Cannot choose from empty sequence") |
| 202 | + rnd = self.random() |
| 203 | + return rnd.choice(sequence) |
0 commit comments