requence 0.8.1.dev62__tar.gz → 0.8.1.dev64__tar.gz

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 (79) hide show
  1. {requence-0.8.1.dev62/requence.egg-info → requence-0.8.1.dev64}/PKG-INFO +67 -1
  2. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/README.md +66 -0
  3. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/pyproject.toml +1 -1
  4. requence-0.8.1.dev64/requence/callbacks/context.py +40 -0
  5. requence-0.8.1.dev64/requence/callbacks/handler.py +102 -0
  6. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/internal_types.py +6 -1
  7. requence-0.8.1.dev64/requence/requence_callback.py +84 -0
  8. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/service/__init__.py +234 -17
  9. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/service/boundary.py +14 -2
  10. requence-0.8.1.dev64/requence/service/callback_growth.py +218 -0
  11. requence-0.8.1.dev64/requence/service/durable_callback.py +191 -0
  12. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/service/surface_handler.py +14 -0
  13. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/wire.py +125 -4
  14. {requence-0.8.1.dev62 → requence-0.8.1.dev64/requence.egg-info}/PKG-INFO +67 -1
  15. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence.egg-info/SOURCES.txt +2 -0
  16. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/tests/test_wire.py +59 -0
  17. requence-0.8.1.dev62/requence/callbacks/context.py +0 -25
  18. requence-0.8.1.dev62/requence/callbacks/handler.py +0 -56
  19. requence-0.8.1.dev62/requence/requence_callback.py +0 -22
  20. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/MANIFEST.in +0 -0
  21. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/__init__.py +0 -0
  22. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/callbacks/__init__.py +0 -0
  23. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/client_properties.py +0 -0
  24. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/context.py +0 -0
  25. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/exceptions.py +0 -0
  26. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/__init__.py +0 -0
  27. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/errors.py +0 -0
  28. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/handlers/__init__.py +0 -0
  29. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/handlers/claim_check_handler.py +0 -0
  30. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/handlers/context.py +0 -0
  31. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/handlers/file_handler.py +0 -0
  32. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/handlers/stream_handler.py +0 -0
  33. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/pending_uploads.py +0 -0
  34. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/requence_file.py +0 -0
  35. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/requence_stream.py +0 -0
  36. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/sanitize_log_data.py +0 -0
  37. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/stream_framing.py +0 -0
  38. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/files/transport.py +0 -0
  39. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/logger.py +0 -0
  40. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/obfuscase.py +0 -0
  41. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/py.typed +0 -0
  42. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/reachable.py +0 -0
  43. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/requence_file.py +0 -0
  44. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/requence_stream.py +0 -0
  45. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/service/cli.py +0 -0
  46. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/service/transformer.py +0 -0
  47. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/service/types.py +0 -0
  48. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/service/ui.py +0 -0
  49. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/service/ui_watch.py +0 -0
  50. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/__init__.py +0 -0
  51. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/abort_task.py +0 -0
  52. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/ack_task.py +0 -0
  53. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/cli.py +0 -0
  54. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/get_task.py +0 -0
  55. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/ingress.py +0 -0
  56. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/protect_task.py +0 -0
  57. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/task.py +0 -0
  58. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/task_watcher.py +0 -0
  59. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/types.py +0 -0
  60. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/updates.py +0 -0
  61. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/task/utils.py +0 -0
  62. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/transformer/__init__.py +0 -0
  63. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/transformer/context.py +0 -0
  64. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/transformer/errors.py +0 -0
  65. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/transformer/guards.py +0 -0
  66. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/transformer/message_handler.py +0 -0
  67. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/transformer/transform.py +0 -0
  68. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/transformer/value_handler.py +0 -0
  69. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/transformer/walk.py +0 -0
  70. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/utils.py +0 -0
  71. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence/wire_codec.py +0 -0
  72. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence.egg-info/dependency_links.txt +0 -0
  73. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence.egg-info/entry_points.txt +0 -0
  74. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence.egg-info/requires.txt +0 -0
  75. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/requence.egg-info/top_level.txt +0 -0
  76. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/setup.cfg +0 -0
  77. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/tests/test_client_properties.py +0 -0
  78. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/tests/test_logger.py +0 -0
  79. {requence-0.8.1.dev62 → requence-0.8.1.dev64}/tests/test_wire_codec.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: requence
3
- Version: 0.8.1.dev62
3
+ Version: 0.8.1.dev64
4
4
  Summary: Requence Service
5
5
  Author: Torsten Blindert
6
6
  Requires-Python: >=3.12
@@ -269,6 +269,72 @@ The generator is stopped automatically when `ctx.terminated` is set. Any yielded
269
269
 
270
270
  ---
271
271
 
272
+ ## Callbacks — functions you emit alongside your data
273
+
274
+ A callable in what a service emits arrives downstream as a function the graph may
275
+ call back. There are **two kinds**, and — as with a surface's handler props — you
276
+ pick by *where you write it*: inline in the handler ⇒ **connection-bound**, declared
277
+ at module scope ⇒ **durable**.
278
+
279
+ The TypeScript SDK (`packages/service/README.md`) is the reference for that
280
+ behaviour and for every rule around it — what a durable callback is handed and what
281
+ it is not, what a binding may not be, the per-version queue and its TTL, the pile-up
282
+ warning and its thresholds, and the gaps. The design authority is
283
+ [`knowledge/durable-callbacks.md`](../knowledge/durable-callbacks.md). The wire is
284
+ identical: a Python service and a TS service emit the same references. This section
285
+ is the Python API and the places it differs.
286
+
287
+ ```python
288
+ from requence.service import Service, create_durable_callback
289
+
290
+ # DURABLE. Declared ONCE at module scope, addressed by the name it is given.
291
+ # It closes over nothing per email, so any instance of this version can run it —
292
+ # this one, or the one that replaces it in a redeploy.
293
+ delete_mail = create_durable_callback(
294
+ "deleteMail",
295
+ lambda _arg, context: delete(context["configuration"], context["uid"]),
296
+ )
297
+
298
+ def handler(ctx):
299
+ for mail in mails:
300
+ yield {
301
+ "subject": mail.subject,
302
+ # a reference, not a closure: the registry holds one callback, not one
303
+ # per email.
304
+ "delete": delete_mail.for_({"uid": mail.uid}),
305
+ # CONNECTION-BOUND. Needs the LIVE imap client, so it correctly dies
306
+ # with this message — and holds everything it captured until then.
307
+ "stream": lambda _arg: imap.download(mail.uid),
308
+ }
309
+ ```
310
+
311
+ A declaration with nothing to bind is emitted as itself — `.for_()` is optional
312
+ there:
313
+
314
+ ```python
315
+ acknowledge = create_durable_callback("acknowledge", lambda _arg, _ctx: ack())
316
+
317
+ yield {"subject": mail.subject, "acknowledge": acknowledge}
318
+ ```
319
+
320
+ ### Differences from the TypeScript SDK
321
+
322
+ Both SDKs speak one wire contract; three things cannot be shared.
323
+
324
+ - **`.for_(…)`, not `.for(…)`.** `for` is a reserved word in Python, and PEP 8's
325
+ trailing underscore is the convention for exactly this clash. It is the only place
326
+ the two SDKs deliberately differ in spelling.
327
+ - **The handler's context is a mapping**, read by key — `context["uid"]`,
328
+ `context["configuration"]` — where TypeScript destructures an object. It holds the
329
+ same two things and the same reserved key.
330
+ - **No typing of the argument, the binding or the configuration.** TypeScript gets
331
+ all three from `createDurableCallback<Arg, Bound, 'version'>` and refuses a
332
+ declaration emitted without its binding at compile time. In Python `arg` and
333
+ `context` are plain values: the reserved-key and non-dict checks raise at
334
+ `.for_(…)`, and everything else is yours to validate.
335
+
336
+ ---
337
+
272
338
  ## Deferred Delivery via `service.act()`
273
339
 
274
340
  After deferring a message with `ctx.defer()`, deliver the result later — even from a different process — using the `act()` method on the `Service` instance.
@@ -257,6 +257,72 @@ The generator is stopped automatically when `ctx.terminated` is set. Any yielded
257
257
 
258
258
  ---
259
259
 
260
+ ## Callbacks — functions you emit alongside your data
261
+
262
+ A callable in what a service emits arrives downstream as a function the graph may
263
+ call back. There are **two kinds**, and — as with a surface's handler props — you
264
+ pick by *where you write it*: inline in the handler ⇒ **connection-bound**, declared
265
+ at module scope ⇒ **durable**.
266
+
267
+ The TypeScript SDK (`packages/service/README.md`) is the reference for that
268
+ behaviour and for every rule around it — what a durable callback is handed and what
269
+ it is not, what a binding may not be, the per-version queue and its TTL, the pile-up
270
+ warning and its thresholds, and the gaps. The design authority is
271
+ [`knowledge/durable-callbacks.md`](../knowledge/durable-callbacks.md). The wire is
272
+ identical: a Python service and a TS service emit the same references. This section
273
+ is the Python API and the places it differs.
274
+
275
+ ```python
276
+ from requence.service import Service, create_durable_callback
277
+
278
+ # DURABLE. Declared ONCE at module scope, addressed by the name it is given.
279
+ # It closes over nothing per email, so any instance of this version can run it —
280
+ # this one, or the one that replaces it in a redeploy.
281
+ delete_mail = create_durable_callback(
282
+ "deleteMail",
283
+ lambda _arg, context: delete(context["configuration"], context["uid"]),
284
+ )
285
+
286
+ def handler(ctx):
287
+ for mail in mails:
288
+ yield {
289
+ "subject": mail.subject,
290
+ # a reference, not a closure: the registry holds one callback, not one
291
+ # per email.
292
+ "delete": delete_mail.for_({"uid": mail.uid}),
293
+ # CONNECTION-BOUND. Needs the LIVE imap client, so it correctly dies
294
+ # with this message — and holds everything it captured until then.
295
+ "stream": lambda _arg: imap.download(mail.uid),
296
+ }
297
+ ```
298
+
299
+ A declaration with nothing to bind is emitted as itself — `.for_()` is optional
300
+ there:
301
+
302
+ ```python
303
+ acknowledge = create_durable_callback("acknowledge", lambda _arg, _ctx: ack())
304
+
305
+ yield {"subject": mail.subject, "acknowledge": acknowledge}
306
+ ```
307
+
308
+ ### Differences from the TypeScript SDK
309
+
310
+ Both SDKs speak one wire contract; three things cannot be shared.
311
+
312
+ - **`.for_(…)`, not `.for(…)`.** `for` is a reserved word in Python, and PEP 8's
313
+ trailing underscore is the convention for exactly this clash. It is the only place
314
+ the two SDKs deliberately differ in spelling.
315
+ - **The handler's context is a mapping**, read by key — `context["uid"]`,
316
+ `context["configuration"]` — where TypeScript destructures an object. It holds the
317
+ same two things and the same reserved key.
318
+ - **No typing of the argument, the binding or the configuration.** TypeScript gets
319
+ all three from `createDurableCallback<Arg, Bound, 'version'>` and refuses a
320
+ declaration emitted without its binding at compile time. In Python `arg` and
321
+ `context` are plain values: the reserved-key and non-dict checks raise at
322
+ `.for_(…)`, and everything else is yours to validate.
323
+
324
+ ---
325
+
260
326
  ## Deferred Delivery via `service.act()`
261
327
 
262
328
  After deferring a message with `ctx.defer()`, deliver the result later — even from a different process — using the `act()` method on the `Service` instance.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "requence"
7
- version = "0.8.1.dev62"
7
+ version = "0.8.1.dev64"
8
8
  description = "Requence Service"
9
9
  readme = { file = "README.md", content-type = "text/markdown" }
10
10
  authors = [{ name = "Torsten Blindert" }]
@@ -0,0 +1,40 @@
1
+ """Capability contexts of the callback handler (mirrors packages/callbacks/src/context.ts).
2
+
3
+ Documentation + optional static typing — see ``requence/files/handlers/context.py``
4
+ for how ctx capabilities work on the Python side.
5
+ """
6
+
7
+ from typing import Any, Callable, Protocol, TypedDict
8
+
9
+
10
+ class CallbackRegistration(TypedDict):
11
+ callbackId: str
12
+ sourceId: str
13
+
14
+
15
+ class CallbackEgressContext(Protocol):
16
+ # Registrar for this emission; absent ⇒ callables fail loud.
17
+ #
18
+ # The position comes along because a registry that grows is only actionable
19
+ # with it (#151): "you hold 50 000 callbacks" does not say which `yield`, and
20
+ # the handler already holds the path — it writes it into ``propertyPath`` on
21
+ # the very next line. A registrar that does not care may ignore it; nothing
22
+ # about the reference it returns depends on it.
23
+ on_callback: Callable[[Callable[[Any], None], list[str | int]], CallbackRegistration] | None
24
+ # The emission the value belongs to (embedded in callback references).
25
+ output_name: str | None
26
+ # The node this boundary emits for, as the operator dispatched it. Stamped
27
+ # into a **durable** reference, which is addressed by the emitting node rather
28
+ # than by a connection (#150) — so a boundary that cannot say which node it is
29
+ # cannot mint one, and the handler raises instead of emitting a reference
30
+ # nothing could route.
31
+ #
32
+ # Constant for every send of one message, unlike ``output_name``, so egress
33
+ # owners set it once when the boundary is built.
34
+ node_id: str | None
35
+
36
+
37
+ class CallbackIngressContext(Protocol):
38
+ # Invocation dispatch for reconstructed callbacks; payload is the
39
+ # CallbackObject plus {"arg": ...}. Absent ⇒ invoking is a no-op.
40
+ on_callback_invoke: Callable[[dict], None] | None
@@ -0,0 +1,102 @@
1
+ """Bidirectional handler owning the ``RequenceCallback`` reference tag
2
+ (mirrors packages/callbacks/src/handler.ts).
3
+
4
+ Egress serializes any callable into a full callback reference: identity
5
+ (``callbackId``/``sourceId``) comes from ``ctx.on_callback``, the emission
6
+ from ``ctx.output_name``, and the position from the walk's ``path`` — the
7
+ reference's public identity (the operator validates invocation args against
8
+ the output schema at ``propertyPath``). A boundary that cannot register
9
+ callbacks (no ``ctx.on_callback``) fails loud.
10
+
11
+ A callable reaching this handler is a closure in the running process, so the
12
+ reference it mints is ``lifetime: 'connection'`` — the discriminator is stated
13
+ rather than implied, because a reference that omits it does not parse
14
+ (``wire.py``).
15
+
16
+ The one exception is a value the author minted with ``.for_(bound)``, which is a
17
+ callable only so that the walk offers it here at all (#147): it is already a
18
+ *reference* to a declaration and registers nothing, so it takes the durable arm
19
+ and this boundary's registry never grows by it. That is the whole point — a
20
+ three-week receiver's registry stays the size of its source rather than the size
21
+ of its traffic. Both arms are completed the same way, with the position the walk
22
+ knows and the emission the ctx knows.
23
+
24
+ Ingress reconstructs the reference into a callable that dispatches through
25
+ ``ctx.on_callback_invoke`` — with no ``on_callback_invoke`` provided, invoking
26
+ the callback is a no-op; callers that forbid callbacks pass a raising
27
+ implementation.
28
+ """
29
+
30
+ from typing import Any
31
+
32
+ from ..requence_callback import read_durable_callback_binding
33
+ from ..transformer import TransformContext, TransformPath, ValueHandler
34
+ from ..wire import REFERENCE_TAG_KEY, is_callback_object
35
+
36
+
37
+ def _serialize(callback: Any, ctx: TransformContext, path: TransformPath) -> dict:
38
+ binding = read_durable_callback_binding(callback)
39
+ if binding is not None:
40
+ # No ``ctx.on_callback`` check: a boundary that cannot register callbacks
41
+ # is refusing to hold a closure for the life of a message, and a durable
42
+ # reference asks nobody to hold anything. It addresses the service VERSION,
43
+ # which outlives every boundary here.
44
+ #
45
+ # ``ctx.node_id`` IS checked, because it is the whole address on the way
46
+ # back: the operator routes a durable invocation to the emitting node's
47
+ # version and hands the handler that node's configuration (#150). A
48
+ # reference minted without it would parse nowhere and be silently
49
+ # un-invokable, which is the failure this feature exists to remove — so it
50
+ # is named here, in the process that emitted it.
51
+ node_id = getattr(ctx, "node_id", None)
52
+ if not node_id:
53
+ raise Exception(
54
+ f'durable callback "{binding.name}" cannot be emitted on this '
55
+ f'boundary (no ctx.node_id) at path "{".".join(map(str, path))}"'
56
+ )
57
+ return {
58
+ REFERENCE_TAG_KEY: "RequenceCallback",
59
+ "lifetime": "durable",
60
+ "name": binding.name,
61
+ "nodeId": node_id,
62
+ "bound": binding.bound,
63
+ "outputName": getattr(ctx, "output_name", None),
64
+ "propertyPath": list(path),
65
+ }
66
+
67
+ on_callback = getattr(ctx, "on_callback", None)
68
+ if on_callback is None:
69
+ # handler raises are not path-wrapped by the transformer — carry the
70
+ # position in the message ourselves
71
+ raise Exception(
72
+ "functions are not serializable on this boundary (no ctx.on_callback) "
73
+ f'at path "{".".join(map(str, path))}"'
74
+ )
75
+ return {
76
+ # The path goes with the callable: the registrar counts per position, so a
77
+ # registry that grows can name the `yield` doing it (#151).
78
+ **on_callback(callback, list(path)),
79
+ "lifetime": "connection",
80
+ "outputName": getattr(ctx, "output_name", None),
81
+ "propertyPath": list(path),
82
+ REFERENCE_TAG_KEY: "RequenceCallback",
83
+ }
84
+
85
+
86
+ def _deserialize(ref: dict, ctx: TransformContext, _path: TransformPath):
87
+ def invoke(arg: Any) -> None:
88
+ on_callback_invoke = getattr(ctx, "on_callback_invoke", None)
89
+ if on_callback_invoke is not None:
90
+ on_callback_invoke({**ref, "arg": arg})
91
+
92
+ return invoke
93
+
94
+
95
+ def create_requence_callback_handler() -> ValueHandler:
96
+ return ValueHandler(
97
+ tag="RequenceCallback",
98
+ can_handle=callable,
99
+ serialize=_serialize,
100
+ is_reference=is_callback_object,
101
+ deserialize=_deserialize,
102
+ )
@@ -1,4 +1,4 @@
1
- from typing import Optional, TypedDict, Any, Callable, Union
1
+ from typing import NotRequired, Optional, TypedDict, Any, Callable, Union
2
2
  from ssl import SSLContext
3
3
 
4
4
  class ServiceConfig(TypedDict, total=False):
@@ -25,6 +25,11 @@ class TaskOptions(TypedDict, total=False):
25
25
  class Payload(TypedDict, total=True):
26
26
  input: Any
27
27
  configuration: Any
28
+ # Which node of the graph this dispatch is for — the address a durable
29
+ # callback reference carries out with it (#150). NotRequired because a
30
+ # dispatch minted before it existed carries none, and that message simply
31
+ # cannot emit one.
32
+ nodeId: NotRequired[str]
28
33
  options: TaskOptions
29
34
 
30
35
  class ActorApi(TypedDict):
@@ -0,0 +1,84 @@
1
+ from .exceptions import StopException
2
+ from dataclasses import dataclass
3
+ from threading import Event
4
+ from typing import Any, Generic, TypeVar, Callable, Optional, Union
5
+
6
+ T = TypeVar('T')
7
+ class Callback(Generic[T]):
8
+ def __init__(self, callback: Optional[Callable[[T], None]] = None):
9
+ self.__event = Event()
10
+ self.__result: Optional[Union[T, StopException]] = None
11
+ self.__callback = callback
12
+
13
+ def __call__(self, arg: Union[T, StopException]):
14
+ self.__result = arg
15
+ self.__event.set()
16
+ if self.__callback and not isinstance(arg, StopException):
17
+ self.__callback(arg)
18
+
19
+ def response(self) -> T:
20
+ self.__event.wait()
21
+ if (isinstance(self.__result, StopException)):
22
+ raise self.__result
23
+ return self.__result # type: ignore
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class DurableCallbackBinding:
28
+ """What a ``.for_(bound)`` reference carries before the boundary completes it:
29
+ the declaration's name and the data bound to this emission. The position
30
+ (``outputName``/``propertyPath``) is added where it is known — the value walk —
31
+ exactly as it is for the connection arm."""
32
+
33
+ name: str
34
+ bound: Any
35
+
36
+
37
+ # Where a ``.for_(bound)`` reference keeps its binding.
38
+ #
39
+ # A dunder-ish attribute name rather than a private one, and read structurally
40
+ # below rather than by ``isinstance``: two copies of this package in one process (a
41
+ # service depending on an SDK that depends on it) must agree, which is the same
42
+ # reason the TS side uses ``Symbol.for`` rather than a fresh symbol. The name is
43
+ # long enough that an author's own callable cannot carry one by accident.
44
+ _DURABLE_CALLBACK_BINDING = "__requence_durable_callback_binding__"
45
+
46
+
47
+ def create_durable_callback_reference(binding: DurableCallbackBinding) -> Callable[..., Any]:
48
+ """Mints the value an author emits in place of a closure — what
49
+ ``create_durable_callback(...).for_(bound)`` returns (#147).
50
+
51
+ It is a **callable** carrying the binding on an attribute, rather than the wire
52
+ object it will become, for the reason the TS side mints a function: the egress
53
+ walk only offers *complex* values to a handler, and a plain dict is traversable
54
+ structure — a literal reference would be walked straight through and emitted
55
+ without the ``outputName``/``propertyPath`` the operator validates against,
56
+ which no schema parse downstream would accept. A callable is what the callback
57
+ handler claims.
58
+
59
+ Calling it *here*, in the emitting service, is the author's mistake — a durable
60
+ callback runs where the invocation is delivered, never inline — so it says so
61
+ rather than doing nothing."""
62
+
63
+ def reference(*_args: Any, **_kwargs: Any) -> Any:
64
+ raise Exception(
65
+ f'durable callback "{binding.name}" was called in the service that '
66
+ "emitted it — a durable callback reference is a value to emit, and it "
67
+ "runs only when the graph invokes it"
68
+ )
69
+
70
+ # Named after the callback, not after this closure. It costs nothing and it is
71
+ # what a traceback and a debugger read.
72
+ reference.__name__ = binding.name
73
+ reference.__qualname__ = binding.name
74
+ setattr(reference, _DURABLE_CALLBACK_BINDING, binding)
75
+ return reference
76
+
77
+
78
+ def read_durable_callback_binding(value: Any) -> Optional[DurableCallbackBinding]:
79
+ """The binding a value carries, or ``None`` when it is an ordinary callable —
80
+ which is how the callback handler tells the two lifetimes apart on egress."""
81
+ if not callable(value):
82
+ return None
83
+ binding = getattr(value, _DURABLE_CALLBACK_BINDING, None)
84
+ return binding if isinstance(getattr(binding, "name", None), str) else None