synadia-durable 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. synadia_durable/__init__.py +119 -0
  2. synadia_durable/_engine/__init__.py +6 -0
  3. synadia_durable/_engine/blobs.py +277 -0
  4. synadia_durable/_engine/client.py +305 -0
  5. synadia_durable/_engine/errors.py +219 -0
  6. synadia_durable/_engine/names.py +39 -0
  7. synadia_durable/_engine/payload.py +203 -0
  8. synadia_durable/_engine/transport.py +231 -0
  9. synadia_durable/_engine/worker.py +1020 -0
  10. synadia_durable/_internal/__init__.py +1 -0
  11. synadia_durable/_internal/backoff.py +22 -0
  12. synadia_durable/_internal/invariant.py +43 -0
  13. synadia_durable/_internal/json.py +76 -0
  14. synadia_durable/_internal/logger.py +53 -0
  15. synadia_durable/_internal/metrics.py +94 -0
  16. synadia_durable/_internal/token.py +29 -0
  17. synadia_durable/_nats/__init__.py +6 -0
  18. synadia_durable/_nats/connect.py +29 -0
  19. synadia_durable/_nats/protocol.py +106 -0
  20. synadia_durable/core/__init__.py +6 -0
  21. synadia_durable/core/children.py +54 -0
  22. synadia_durable/core/ctx.py +1297 -0
  23. synadia_durable/core/execute.py +268 -0
  24. synadia_durable/core/inbound.py +194 -0
  25. synadia_durable/core/registry.py +65 -0
  26. synadia_durable/core/scheduler.py +36 -0
  27. synadia_durable/core/work_item.py +57 -0
  28. synadia_durable/core/workflow.py +61 -0
  29. synadia_durable/errors.py +228 -0
  30. synadia_durable/journal/__init__.py +1 -0
  31. synadia_durable/journal/blobs.py +551 -0
  32. synadia_durable/journal/codec.py +103 -0
  33. synadia_durable/journal/entry.py +372 -0
  34. synadia_durable/journal/payload_codec.py +98 -0
  35. synadia_durable/journal/store.py +182 -0
  36. synadia_durable/py.typed +0 -0
  37. synadia_durable/types.py +258 -0
  38. synadia_durable/version.py +26 -0
  39. synadia_durable-0.2.0.dist-info/METADATA +179 -0
  40. synadia_durable-0.2.0.dist-info/RECORD +42 -0
  41. synadia_durable-0.2.0.dist-info/WHEEL +4 -0
  42. synadia_durable-0.2.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,119 @@
1
+ """synadia-durable — the thin durable execution SDK: the replay core in your process,
2
+ ``durable-engine`` behind it.
3
+
4
+ A workflow is an ordinary ``async`` function whose every nondeterministic or side-effecting
5
+ operation goes through ``ctx`` and is journaled; on a crash the function re-runs from the top,
6
+ journaled operations replay, and the first un-journaled one is the live frontier. The replay core is
7
+ copied from the retired library (``synadia-durable``), edited since; behind its three seams and the
8
+ client's five calls sits a request/reply client for ``durable-engine``, which owns the streams.
9
+
10
+ The wire contract is the protocol's journal format and the engine's API (its ``API.md``, delivered
11
+ with the engine), the same as the TypeScript SDK's, so runs, signals and sub-workflow calls cross
12
+ the language boundary.
13
+ """
14
+
15
+ from synadia_durable._engine.client import Client, RunHandle, create_client
16
+ from synadia_durable._engine.errors import (
17
+ EngineError,
18
+ EngineFencedError,
19
+ EngineUnavailableError,
20
+ InvalidRequestError,
21
+ LeaseExpiredError,
22
+ LimitError,
23
+ RunNotFoundError,
24
+ UnsupportedEngineError,
25
+ )
26
+ from synadia_durable._engine.worker import PumpHealth, Worker, WorkerHealth, create_worker
27
+ from synadia_durable._internal.logger import Logger, StdlibLogger
28
+ from synadia_durable._internal.metrics import Metrics, SilentMetrics
29
+ from synadia_durable._nats.connect import RECONNECT_DEFAULTS, with_reconnect_defaults
30
+ from synadia_durable.core.workflow import define_workflow, workflow
31
+ from synadia_durable.errors import (
32
+ BlobIntegrityError,
33
+ BlobMissingError,
34
+ CancelledError,
35
+ ConnectionClosedError,
36
+ DurableError,
37
+ DurableTimeoutError,
38
+ FencedError,
39
+ NonDeterminismError,
40
+ NotImplementedFeatureError,
41
+ PayloadCodecError,
42
+ PayloadTooLargeError,
43
+ SerializationError,
44
+ StepNestingError,
45
+ WorkflowFailure,
46
+ )
47
+ from synadia_durable.journal.blobs import OffloadOptions
48
+ from synadia_durable.journal.payload_codec import PayloadCodec, aes_gcm_payload_codec
49
+ from synadia_durable.types import (
50
+ Ctx,
51
+ DurableFuture,
52
+ Handle,
53
+ RetryPolicy,
54
+ RunState,
55
+ RunStatus,
56
+ StartOptions,
57
+ Workflow,
58
+ )
59
+ from synadia_durable.version import (
60
+ VERSION,
61
+ WIRE_VERSION,
62
+ WIRE_VERSION_BLOBS,
63
+ WIRE_VERSION_ENCODED,
64
+ )
65
+
66
+ __all__ = [
67
+ "RECONNECT_DEFAULTS",
68
+ "VERSION",
69
+ "WIRE_VERSION",
70
+ "WIRE_VERSION_BLOBS",
71
+ "WIRE_VERSION_ENCODED",
72
+ "BlobIntegrityError",
73
+ "BlobMissingError",
74
+ "CancelledError",
75
+ "Client",
76
+ "ConnectionClosedError",
77
+ "Ctx",
78
+ "DurableError",
79
+ "DurableFuture",
80
+ "DurableTimeoutError",
81
+ "EngineError",
82
+ "EngineFencedError",
83
+ "EngineUnavailableError",
84
+ "FencedError",
85
+ "Handle",
86
+ "InvalidRequestError",
87
+ "LeaseExpiredError",
88
+ "LimitError",
89
+ "Logger",
90
+ "Metrics",
91
+ "NonDeterminismError",
92
+ "NotImplementedFeatureError",
93
+ "OffloadOptions",
94
+ "PayloadCodec",
95
+ "PayloadCodecError",
96
+ "PayloadTooLargeError",
97
+ "PumpHealth",
98
+ "RetryPolicy",
99
+ "RunHandle",
100
+ "RunNotFoundError",
101
+ "RunState",
102
+ "RunStatus",
103
+ "SerializationError",
104
+ "SilentMetrics",
105
+ "StartOptions",
106
+ "StdlibLogger",
107
+ "StepNestingError",
108
+ "UnsupportedEngineError",
109
+ "Worker",
110
+ "WorkerHealth",
111
+ "Workflow",
112
+ "WorkflowFailure",
113
+ "aes_gcm_payload_codec",
114
+ "create_client",
115
+ "create_worker",
116
+ "define_workflow",
117
+ "with_reconnect_defaults",
118
+ "workflow",
119
+ ]
@@ -0,0 +1,6 @@
1
+ """synadia-durable — the engine client: the only package that speaks to the broker at all.
2
+
3
+ One request to ``{prefix}.api.v1.<op>`` per call (the engine's ``API.md``), through
4
+ ``nats-py``'s core request/reply. The streams, buckets and consumers behind the API are the
5
+ engine's. Mirrors ``src/engine/`` of the TypeScript SDK, module for module.
6
+ """
@@ -0,0 +1,277 @@
1
+ """synadia-durable — the SDK half of the chunked upload and download (the engine's
2
+ ``API.md`` "Sizes", ``put``, ``get``; the engine's findings F25, this repo's F1). Mirrors
3
+ ``src/engine/blobs.ts``.
4
+
5
+ A value whose request would pass ``request_max`` goes up in ``put`` parts first and travels as the
6
+ ref the engine answers; a ref the engine hands back because a value would not fit a reply comes down
7
+ in ``get`` parts, its digest checked. Both directions run through the library's own offload code
8
+ (``offload_entry``, ``store_payload_blob``, ``resolve_entry`` of ``journal/blobs.py``) with the
9
+ engine as its blob store, so a ref, its name (``{runId}/sha256:<hex>``), its ``v:2`` / ``v:3``
10
+ marking and its digest check are the library's bytes. The pure core never sees a ref: the worker's
11
+ journal is resolved before replay.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import base64
17
+ import json
18
+ import math
19
+ import time
20
+ import uuid
21
+ from dataclasses import dataclass
22
+ from typing import TYPE_CHECKING, Any, Protocol
23
+
24
+ from synadia_durable._engine.errors import EngineUnavailableError, InvalidRequestError
25
+ from synadia_durable._engine.transport import REQUEST_MARGIN_MS
26
+ from synadia_durable._internal.metrics import Metrics, emit_safe
27
+ from synadia_durable.errors import BlobMissingError, PayloadTooLargeError, SerializationError
28
+ from synadia_durable.journal.blobs import digest_of
29
+
30
+ if TYPE_CHECKING:
31
+ from collections.abc import Awaitable, Callable
32
+
33
+ from synadia_durable._engine.names import Op
34
+ from synadia_durable._engine.transport import Transport
35
+ from synadia_durable.journal.entry import BlobRef
36
+
37
+ __all__ = [
38
+ "PUT_MS_PER_MIB",
39
+ "PUT_RTTS_PER_CHUNK",
40
+ "STORE_CHUNK_BYTES",
41
+ "EngineBlobs",
42
+ "Sizes",
43
+ "body_bytes",
44
+ "part_bytes_of",
45
+ "put_timeout_ms",
46
+ "run_of_blob",
47
+ ]
48
+
49
+ #: The headroom the engine keeps under max_payload for a request's envelope (API.md "Sizes").
50
+ _REQUEST_HEADROOM = 16 * 1024
51
+
52
+
53
+ def part_bytes_of(request_max: int) -> int:
54
+ """``(request_max − 4096) / 4 × 3``: one part's raw bytes, base64 of which fits a request."""
55
+ return (request_max - 4096) // 4 * 3
56
+
57
+
58
+ @dataclass(frozen=True, slots=True)
59
+ class Limits:
60
+ """What ``info``'s ``limits`` says a request may weigh, and the raw bytes of one ``put`` part."""
61
+
62
+ request_max: int
63
+ part_bytes: int
64
+
65
+
66
+ class Sizes:
67
+ """The connection's sizes, from the engine's ``info`` once per transport (and from the server's
68
+ max_payload less the engine's headroom while no engine has answered)."""
69
+
70
+ def __init__(self, request: Transport, max_payload: Callable[[], int]) -> None:
71
+ self._request = request
72
+ self._max_payload = max_payload
73
+ self._known: Limits | None = None
74
+
75
+ async def __call__(self) -> Limits:
76
+ if self._known is not None:
77
+ return self._known
78
+ try:
79
+ r = await self._request.request("info", {})
80
+ rm = (r.get("limits") or {}).get("request_max")
81
+ if isinstance(rm, int) and rm > 4096:
82
+ self._known = Limits(rm, part_bytes_of(rm))
83
+ return self._known
84
+ except Exception: # noqa: BLE001 — the fallback below; the request itself will say
85
+ pass
86
+ rm = max(8 * 1024, (self._max_payload() or 1024 * 1024) - _REQUEST_HEADROOM)
87
+ return Limits(rm, part_bytes_of(rm))
88
+
89
+
90
+ #: The engine's object-store chunk: one acked publish each, so one dependent round trip each.
91
+ STORE_CHUNK_BYTES = 128 * 1024
92
+ #: Round trips allowed per chunk the engine stores, reads back or deletes for a ``put``.
93
+ PUT_RTTS_PER_CHUNK = 4
94
+ #: The slowest store a ``put`` waits for: a MiB of what the engine moves per this many ms.
95
+ PUT_MS_PER_MIB = 1_000
96
+
97
+
98
+ def put_timeout_ms(stored: int, rtt_ms: float) -> int:
99
+ """How long a ``put`` part may take to answer (this repo's F33). A part is staged in the blob
100
+ store before it is answered; the last one is answered once the engine has read every part back,
101
+ checked the digest, written the blob and deleted the parts (API.md ``put``). So the wait grows
102
+ with the bytes the engine moves for it (``stored``: the part's own, plus the value twice on the
103
+ last), at a round trip per store chunk and a floor on the store's throughput, over the margin
104
+ every request gets. A slow store is waited for, not refused. Mirrors ``putTimeoutMs``."""
105
+ chunks = -(-stored // STORE_CHUNK_BYTES)
106
+ return math.ceil(
107
+ REQUEST_MARGIN_MS
108
+ + chunks * PUT_RTTS_PER_CHUNK * max(0.0, rtt_ms)
109
+ + stored / (1024 * 1024) * PUT_MS_PER_MIB
110
+ )
111
+
112
+
113
+ def _deterministic_put(run_id: str, size: int, part: int, e: Exception) -> Exception:
114
+ """A ``put`` that the engine did not answer within its size-scaled wait, or refused as
115
+ malformed, is deterministic for this value (this repo's F33): a PayloadTooLargeError or
116
+ SerializationError, which the pure core fails the run on (and a client call raises), rather
117
+ than a transient the item's redelivery would meet again with the same value, for ever. A lease
118
+ that expired, a closed connection, no engine at all and the engine's own ``unavailable`` keep
119
+ their meaning."""
120
+ if isinstance(e, EngineUnavailableError) and e.timed_out:
121
+ return PayloadTooLargeError(
122
+ run_id,
123
+ f"put (run {run_id}): the engine did not store a {size}-byte value in time (part "
124
+ f"{part}); the blob store is too slow for a value this size: {e}",
125
+ )
126
+ if isinstance(e, InvalidRequestError):
127
+ return SerializationError(run_id, f"put (run {run_id}): {e}")
128
+ return e
129
+
130
+
131
+ class BlobRequest(Protocol):
132
+ """The transport's ``request``, or the worker's leased one: a ``put`` gives its own timeout."""
133
+
134
+ def __call__(
135
+ self, op: Op, body: dict[str, Any], /, *, timeout_ms: int | None = None
136
+ ) -> Awaitable[dict[str, Any]]: ...
137
+
138
+
139
+ def run_of_blob(name: str) -> str:
140
+ """The run a blob belongs to: its name is ``{runId}/sha256:<hex>``."""
141
+ return name.split("/", 1)[0] if "/" in name else ""
142
+
143
+
144
+ def body_bytes(body: dict[str, Any]) -> int:
145
+ """The encoded size of a request body, as the transport will send it."""
146
+ return len(
147
+ json.dumps(body, allow_nan=False, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
148
+ )
149
+
150
+
151
+ class EngineBlobs:
152
+ """The engine as the library's ``BlobStore``: ``put`` uploads in parts and checks that the ref the
153
+ engine answers names the same blob; ``get`` downloads in parts, and raises the library's
154
+ :class:`BlobMissingError` when the engine says the blob is gone (``get``'s ``blob_gone``, which
155
+ the transport maps to it), so the worker parks the run; bytes the engine found not to be the
156
+ digest's come up as :class:`BlobIntegrityError`, which parks it the same way.
157
+
158
+ ``lease`` is the item's ``(run_id, lease)`` from an execution: sent with a part of that run's
159
+ blob only (another run's, a child's input, carries none).
160
+ """
161
+
162
+ def __init__(
163
+ self,
164
+ request: BlobRequest,
165
+ sizes: Sizes,
166
+ *,
167
+ lease: tuple[str, str] | None = None,
168
+ metrics: Metrics | None = None,
169
+ rtt: Callable[[], Awaitable[float]] | None = None,
170
+ ) -> None:
171
+ self._request = request
172
+ self._sizes = sizes
173
+ self._lease = lease
174
+ self._metrics = metrics
175
+ #: The connection's round trip in seconds (``nc.rtt``), measured once per upload.
176
+ self._rtt = rtt
177
+
178
+ async def _rtt_ms(self) -> float:
179
+ if self._rtt is None:
180
+ return 0.0
181
+ try:
182
+ return (await self._rtt()) * 1000
183
+ except Exception: # noqa: BLE001 — the request itself will say what is wrong
184
+ return 0.0
185
+
186
+ def _lease_for(self, run_id: str) -> dict[str, str]:
187
+ if self._lease is not None and self._lease[0] == run_id:
188
+ return {"lease": self._lease[1]}
189
+ return {}
190
+
191
+ def _emit(self, name: str, blob: str, size: int, started: float, outcome: str) -> None:
192
+ emit_safe(
193
+ self._metrics,
194
+ name,
195
+ {
196
+ "name": blob,
197
+ "bytes": size,
198
+ "ms": round((time.monotonic() - started) * 1000),
199
+ "outcome": outcome,
200
+ },
201
+ )
202
+
203
+ async def put(self, name: str, data: bytes) -> None:
204
+ """Upload ``data`` as the blob ``name`` (``{runId}/sha256:<hex>``, the library's address)."""
205
+ ref = await self.upload(run_of_blob(name), data)
206
+ if ref["name"] != name:
207
+ raise EngineUnavailableError(
208
+ "put", "internal", f"put: the engine stored {ref['name']}, not {name}"
209
+ )
210
+
211
+ async def upload(self, run_id: str, data: bytes) -> BlobRef:
212
+ """Upload ``data`` into ``run_id``'s namespace in parts; the ref the engine answers."""
213
+ started = time.monotonic()
214
+ digest = digest_of(data)
215
+ name = f"{run_id}/{digest}"
216
+ try:
217
+ part_bytes = (await self._sizes()).part_bytes
218
+ rtt_ms = await self._rtt_ms()
219
+ upload = str(uuid.uuid4())
220
+ last = max(0, -(-len(data) // part_bytes) - 1)
221
+ ref: BlobRef | None = None
222
+ for part in range(last + 1):
223
+ raw = data[part * part_bytes : (part + 1) * part_bytes]
224
+ body: dict[str, Any] = {
225
+ "runId": run_id,
226
+ **self._lease_for(run_id),
227
+ "name": upload,
228
+ "part": part,
229
+ "bytes": base64.b64encode(raw).decode("ascii"),
230
+ }
231
+ stored = len(raw)
232
+ if part == last:
233
+ body |= {"last": True, "digest": digest}
234
+ stored += 2 * len(data)
235
+ try:
236
+ r = await self._request("put", body, timeout_ms=put_timeout_ms(stored, rtt_ms))
237
+ except Exception as e:
238
+ raise _deterministic_put(run_id, len(data), part, e) from e
239
+ ref = r.get("ref")
240
+ if ref is None:
241
+ raise EngineUnavailableError(
242
+ "put", "internal", "put: the last part answered no ref"
243
+ )
244
+ except Exception:
245
+ self._emit("blob.put", name, len(data), started, "error")
246
+ raise
247
+ self._emit("blob.put", name, len(data), started, "ok")
248
+ return ref
249
+
250
+ async def get(self, name: str) -> bytes:
251
+ """Download the blob ``name`` in parts."""
252
+ started = time.monotonic()
253
+ run_id = run_of_blob(name)
254
+ parts: list[bytes] = []
255
+ size = 0
256
+ try:
257
+ part = 0
258
+ while True:
259
+ r = await self._request(
260
+ "get", {"runId": run_id, **self._lease_for(run_id), "name": name, "part": part}
261
+ )
262
+ b = base64.b64decode(r.get("bytes") or "")
263
+ parts.append(b)
264
+ size += len(b)
265
+ if r.get("last") or not b or size >= int(r.get("size", 0)):
266
+ break
267
+ part += 1
268
+ except BlobMissingError:
269
+ # `get` answers `blob_gone` for a blob that is gone (API.md, the engine's F30): a
270
+ # definitive absence, which the transport made the library's BlobMissingError.
271
+ self._emit("blob.get", name, 0, started, "missing")
272
+ raise
273
+ except Exception:
274
+ self._emit("blob.get", name, size, started, "error")
275
+ raise
276
+ self._emit("blob.get", name, size, started, "ok")
277
+ return b"".join(parts)