requence 0.8.1.dev63__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.
- {requence-0.8.1.dev63/requence.egg-info → requence-0.8.1.dev64}/PKG-INFO +67 -1
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/README.md +66 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/pyproject.toml +1 -1
- requence-0.8.1.dev64/requence/callbacks/context.py +40 -0
- requence-0.8.1.dev64/requence/callbacks/handler.py +102 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/internal_types.py +6 -1
- requence-0.8.1.dev64/requence/requence_callback.py +84 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/service/__init__.py +234 -17
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/service/boundary.py +14 -2
- requence-0.8.1.dev64/requence/service/callback_growth.py +218 -0
- requence-0.8.1.dev64/requence/service/durable_callback.py +191 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/service/surface_handler.py +14 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/wire.py +125 -4
- {requence-0.8.1.dev63 → requence-0.8.1.dev64/requence.egg-info}/PKG-INFO +67 -1
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence.egg-info/SOURCES.txt +2 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/tests/test_wire.py +59 -0
- requence-0.8.1.dev63/requence/callbacks/context.py +0 -25
- requence-0.8.1.dev63/requence/callbacks/handler.py +0 -56
- requence-0.8.1.dev63/requence/requence_callback.py +0 -22
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/MANIFEST.in +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/callbacks/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/client_properties.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/context.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/exceptions.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/errors.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/handlers/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/handlers/claim_check_handler.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/handlers/context.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/handlers/file_handler.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/handlers/stream_handler.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/pending_uploads.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/requence_file.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/requence_stream.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/sanitize_log_data.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/stream_framing.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/files/transport.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/logger.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/obfuscase.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/py.typed +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/reachable.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/requence_file.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/requence_stream.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/service/cli.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/service/transformer.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/service/types.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/service/ui.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/service/ui_watch.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/abort_task.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/ack_task.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/cli.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/get_task.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/ingress.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/protect_task.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/task.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/task_watcher.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/types.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/updates.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/task/utils.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/transformer/__init__.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/transformer/context.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/transformer/errors.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/transformer/guards.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/transformer/message_handler.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/transformer/transform.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/transformer/value_handler.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/transformer/walk.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/utils.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence/wire_codec.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence.egg-info/dependency_links.txt +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence.egg-info/entry_points.txt +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence.egg-info/requires.txt +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/requence.egg-info/top_level.txt +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/setup.cfg +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/tests/test_client_properties.py +0 -0
- {requence-0.8.1.dev63 → requence-0.8.1.dev64}/tests/test_logger.py +0 -0
- {requence-0.8.1.dev63 → 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.
|
|
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.
|
|
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
|