|
| 1 | +# Copyright (c) Microsoft Corporation. |
| 2 | +# Licensed under the MIT License. |
| 3 | + |
| 4 | +""" |
| 5 | +Deterministic utilities for Durable Task workflows (async and generator). |
| 6 | +
|
| 7 | +This module provides deterministic alternatives to non-deterministic Python |
| 8 | +functions, ensuring workflow replay consistency across different executions. |
| 9 | +It is shared by both the asyncio authoring model and the generator-based model. |
| 10 | +""" |
| 11 | + |
| 12 | +from __future__ import annotations |
| 13 | + |
| 14 | +import hashlib |
| 15 | +import random |
| 16 | +import string as _string |
| 17 | +import uuid |
| 18 | +from collections.abc import Sequence |
| 19 | +from dataclasses import dataclass |
| 20 | +from datetime import datetime |
| 21 | +from typing import Optional, Protocol, TypeVar, runtime_checkable |
| 22 | + |
| 23 | + |
| 24 | +@dataclass |
| 25 | +class DeterminismSeed: |
| 26 | + """Seed data for deterministic operations.""" |
| 27 | + |
| 28 | + instance_id: str |
| 29 | + orchestration_unix_ts: int |
| 30 | + |
| 31 | + def to_int(self) -> int: |
| 32 | + """Convert seed to integer for PRNG initialization.""" |
| 33 | + combined = f"{self.instance_id}:{self.orchestration_unix_ts}" |
| 34 | + hash_bytes = hashlib.sha256(combined.encode("utf-8")).digest() |
| 35 | + return int.from_bytes(hash_bytes[:8], byteorder="big") |
| 36 | + |
| 37 | + |
| 38 | +def derive_seed(instance_id: str, orchestration_time: datetime) -> int: |
| 39 | + """ |
| 40 | + Derive a deterministic seed from instance ID and orchestration time. |
| 41 | + """ |
| 42 | + ts = int(orchestration_time.timestamp()) |
| 43 | + return DeterminismSeed(instance_id=instance_id, orchestration_unix_ts=ts).to_int() |
| 44 | + |
| 45 | + |
| 46 | +def deterministic_random(instance_id: str, orchestration_time: datetime) -> random.Random: |
| 47 | + """ |
| 48 | + Create a deterministic random number generator. |
| 49 | + """ |
| 50 | + seed = derive_seed(instance_id, orchestration_time) |
| 51 | + return random.Random(seed) |
| 52 | + |
| 53 | + |
| 54 | +def deterministic_uuid4(rnd: random.Random) -> uuid.UUID: |
| 55 | + """Generate a deterministic UUID4 using the provided random generator.""" |
| 56 | + bytes_ = bytes(rnd.randrange(0, 256) for _ in range(16)) |
| 57 | + bytes_list = list(bytes_) |
| 58 | + bytes_list[6] = (bytes_list[6] & 0x0F) | 0x40 # Version 4 |
| 59 | + bytes_list[8] = (bytes_list[8] & 0x3F) | 0x80 # Variant bits |
| 60 | + return uuid.UUID(bytes=bytes(bytes_list)) |
| 61 | + |
| 62 | + |
| 63 | +@runtime_checkable |
| 64 | +class DeterministicContextProtocol(Protocol): |
| 65 | + """Protocol for contexts that provide deterministic operations.""" |
| 66 | + |
| 67 | + @property |
| 68 | + def instance_id(self) -> str: ... |
| 69 | + |
| 70 | + @property |
| 71 | + def current_utc_datetime(self) -> datetime: ... |
| 72 | + |
| 73 | + |
| 74 | +class DeterministicContextMixin: |
| 75 | + """ |
| 76 | + Mixin providing deterministic helpers for workflow contexts. |
| 77 | +
|
| 78 | + Assumes the inheriting class exposes `instance_id` and `current_utc_datetime` attributes. |
| 79 | + """ |
| 80 | + |
| 81 | + def now(self) -> datetime: |
| 82 | + """Return orchestration time (deterministic UTC).""" |
| 83 | + value = self.current_utc_datetime # type: ignore[attr-defined] |
| 84 | + assert isinstance(value, datetime) |
| 85 | + return value |
| 86 | + |
| 87 | + def random(self) -> random.Random: |
| 88 | + """Return a PRNG seeded deterministically from instance id and orchestration time.""" |
| 89 | + rnd = deterministic_random( |
| 90 | + self.instance_id, # type: ignore[attr-defined] |
| 91 | + self.current_utc_datetime, # type: ignore[attr-defined] |
| 92 | + ) |
| 93 | + # Mark as deterministic for sandbox detector whitelisting of bound methods |
| 94 | + try: |
| 95 | + rnd._dt_deterministic = True |
| 96 | + except Exception: |
| 97 | + pass |
| 98 | + return rnd |
| 99 | + |
| 100 | + def uuid4(self) -> uuid.UUID: |
| 101 | + """Return a deterministically generated UUID using the deterministic PRNG.""" |
| 102 | + rnd = self.random() |
| 103 | + return deterministic_uuid4(rnd) |
| 104 | + |
| 105 | + def new_guid(self) -> uuid.UUID: |
| 106 | + """Alias for uuid4 for API parity with other SDKs.""" |
| 107 | + return self.uuid4() |
| 108 | + |
| 109 | + def random_string(self, length: int, *, alphabet: Optional[str] = None) -> str: |
| 110 | + """Return a deterministically generated random string of the given length.""" |
| 111 | + if length < 0: |
| 112 | + raise ValueError("length must be non-negative") |
| 113 | + chars = alphabet if alphabet is not None else (_string.ascii_letters + _string.digits) |
| 114 | + if not chars: |
| 115 | + raise ValueError("alphabet must not be empty") |
| 116 | + rnd = self.random() |
| 117 | + size = len(chars) |
| 118 | + return "".join(chars[rnd.randrange(0, size)] for _ in range(length)) |
| 119 | + |
| 120 | + def random_int(self, min_value: int = 0, max_value: int = 2**31 - 1) -> int: |
| 121 | + """Return a deterministic random integer in the specified range.""" |
| 122 | + if min_value > max_value: |
| 123 | + raise ValueError("min_value must be <= max_value") |
| 124 | + rnd = self.random() |
| 125 | + return rnd.randint(min_value, max_value) |
| 126 | + |
| 127 | + T = TypeVar("T") |
| 128 | + |
| 129 | + def random_choice(self, sequence: Sequence[T]) -> T: |
| 130 | + """Return a deterministic random element from a non-empty sequence.""" |
| 131 | + if not sequence: |
| 132 | + raise IndexError("Cannot choose from empty sequence") |
| 133 | + rnd = self.random() |
| 134 | + return rnd.choice(sequence) |
0 commit comments