requence 0.8.1.dev63__tar.gz → 0.8.1.dev67__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 (84) hide show
  1. requence-0.8.1.dev67/PKG-INFO +137 -0
  2. requence-0.8.1.dev67/README.md +125 -0
  3. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/pyproject.toml +1 -1
  4. requence-0.8.1.dev67/requence/callbacks/context.py +40 -0
  5. requence-0.8.1.dev67/requence/callbacks/handler.py +102 -0
  6. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/context.py +13 -1
  7. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/internal_types.py +17 -1
  8. requence-0.8.1.dev67/requence/requence_callback.py +84 -0
  9. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/__init__.py +296 -18
  10. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/boundary.py +14 -2
  11. requence-0.8.1.dev67/requence/service/callback_growth.py +218 -0
  12. requence-0.8.1.dev67/requence/service/durable_callback.py +191 -0
  13. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/surface_handler.py +14 -0
  14. requence-0.8.1.dev67/requence/store.py +354 -0
  15. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/wire.py +125 -4
  16. requence-0.8.1.dev67/requence.egg-info/PKG-INFO +137 -0
  17. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence.egg-info/SOURCES.txt +4 -0
  18. requence-0.8.1.dev67/tests/test_store_parity.py +377 -0
  19. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/tests/test_wire.py +59 -0
  20. requence-0.8.1.dev63/PKG-INFO +0 -906
  21. requence-0.8.1.dev63/README.md +0 -894
  22. requence-0.8.1.dev63/requence/callbacks/context.py +0 -25
  23. requence-0.8.1.dev63/requence/callbacks/handler.py +0 -56
  24. requence-0.8.1.dev63/requence/requence_callback.py +0 -22
  25. requence-0.8.1.dev63/requence.egg-info/PKG-INFO +0 -906
  26. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/MANIFEST.in +0 -0
  27. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/__init__.py +0 -0
  28. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/callbacks/__init__.py +0 -0
  29. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/client_properties.py +0 -0
  30. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/exceptions.py +0 -0
  31. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/__init__.py +0 -0
  32. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/errors.py +0 -0
  33. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/handlers/__init__.py +0 -0
  34. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/handlers/claim_check_handler.py +0 -0
  35. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/handlers/context.py +0 -0
  36. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/handlers/file_handler.py +0 -0
  37. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/handlers/stream_handler.py +0 -0
  38. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/pending_uploads.py +0 -0
  39. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/requence_file.py +0 -0
  40. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/requence_stream.py +0 -0
  41. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/sanitize_log_data.py +0 -0
  42. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/stream_framing.py +0 -0
  43. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/files/transport.py +0 -0
  44. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/logger.py +0 -0
  45. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/obfuscase.py +0 -0
  46. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/py.typed +0 -0
  47. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/reachable.py +0 -0
  48. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/requence_file.py +0 -0
  49. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/requence_stream.py +0 -0
  50. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/cli.py +0 -0
  51. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/transformer.py +0 -0
  52. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/types.py +0 -0
  53. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/ui.py +0 -0
  54. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/service/ui_watch.py +0 -0
  55. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/__init__.py +0 -0
  56. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/abort_task.py +0 -0
  57. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/ack_task.py +0 -0
  58. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/cli.py +0 -0
  59. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/get_task.py +0 -0
  60. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/ingress.py +0 -0
  61. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/protect_task.py +0 -0
  62. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/task.py +0 -0
  63. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/task_watcher.py +0 -0
  64. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/types.py +0 -0
  65. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/updates.py +0 -0
  66. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/task/utils.py +0 -0
  67. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/__init__.py +0 -0
  68. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/context.py +0 -0
  69. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/errors.py +0 -0
  70. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/guards.py +0 -0
  71. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/message_handler.py +0 -0
  72. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/transform.py +0 -0
  73. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/value_handler.py +0 -0
  74. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/transformer/walk.py +0 -0
  75. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/utils.py +0 -0
  76. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence/wire_codec.py +0 -0
  77. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence.egg-info/dependency_links.txt +0 -0
  78. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence.egg-info/entry_points.txt +0 -0
  79. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence.egg-info/requires.txt +0 -0
  80. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/requence.egg-info/top_level.txt +0 -0
  81. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/setup.cfg +0 -0
  82. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/tests/test_client_properties.py +0 -0
  83. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/tests/test_logger.py +0 -0
  84. {requence-0.8.1.dev63 → requence-0.8.1.dev67}/tests/test_wire_codec.py +0 -0
@@ -0,0 +1,137 @@
1
+ Metadata-Version: 2.4
2
+ Name: requence
3
+ Version: 0.8.1.dev67
4
+ Summary: Requence Service
5
+ Author: Torsten Blindert
6
+ Requires-Python: >=3.12
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: pika>=1.3.2
9
+ Requires-Dist: requests>=2.32.2
10
+ Requires-Dist: sseclient-py>=1.8.0
11
+ Requires-Dist: msgpack>=1.0.5
12
+
13
+ # requence
14
+
15
+ The official Python SDK for the Requence platform. It covers both halves of the integration:
16
+
17
+ - **`requence.service`** — connect a Python service to Requence and process messages
18
+ - **`requence.task`** — start and monitor Requence tasks programmatically
19
+
20
+ > **This README is a getting-started guide.** The reference for both halves lives at
21
+ > **<https://docs.requence.cloud>** — every page has a **Python** tab, including the places
22
+ > where Python's answer differs from TypeScript's.
23
+
24
+ ## Requirements
25
+
26
+ Python 3.12 or later.
27
+
28
+ ## Installation
29
+
30
+ ```bash
31
+ pip install requence
32
+ ```
33
+
34
+ ## Authentication
35
+
36
+ Copy a service's access token from the **Services** list view in the Requence UI
37
+ (**Copy credentials**). A task needs a personal or scoped access token instead.
38
+
39
+ Tokens are resolved in this order:
40
+
41
+ 1. `access_token` passed to `Service()` / `Task()`
42
+ 2. `REQUENCE_SERVICE_ACCESS_TOKEN` / `REQUENCE_TASK_ACCESS_TOKEN`, then `REQUENCE_ACCESS_TOKEN`
43
+ 3. `requence.service_access_token` / `requence.task_access_token`, then `requence.access_token`
44
+ in `pyproject.toml`
45
+
46
+ ```bash
47
+ REQUENCE_SERVICE_ACCESS_TOKEN=your-token python main.py
48
+ ```
49
+
50
+ ## Your first service
51
+
52
+ Create the service in the Requence UI first — its input schema, configuration schema and
53
+ outputs. Then implement the version:
54
+
55
+ ```python
56
+ from requence.service import Service
57
+
58
+ def handler(ctx):
59
+ return {"message": f"Hello, {ctx.input['name']}!"}
60
+
61
+ Service("1.0.0", handler)
62
+ ```
63
+
64
+ > **`Service(...)` never returns.** It consumes on the calling thread, so there is no instance
65
+ > to call `act()` or `close()` on. Use `Service.start(...)` when you need either — it returns
66
+ > the instance once connected, on a daemon consume thread. See
67
+ > [Starting & Stopping][lifecycle].
68
+
69
+ Generate type stubs for `ctx.input`, `ctx.configuration` and `ctx.to_output()` from the schemas
70
+ you defined in the UI:
71
+
72
+ ```bash
73
+ requence-service generate-types
74
+ ```
75
+
76
+ ## Your first task
77
+
78
+ ```python
79
+ from requence.task import Task
80
+
81
+ task = Task(task_template="my-template", input={"name": "World"})
82
+ result = task.sync.result # blocks until the task completes
83
+
84
+ print(result["result"])
85
+ ```
86
+
87
+ `task.sync` holds the blocking accessors; `await task.result` and `async for update in
88
+ task.updates` are the async equivalents.
89
+
90
+ ## Where to read next
91
+
92
+ ### Writing a service
93
+
94
+ | Topic | Page |
95
+ | ----------------------------------------------------------------------- | ------------------------------------------------- |
96
+ | The full walkthrough | [Getting Started][started] |
97
+ | `ctx.input`, `ctx.debug`, `retry`, `abort`, `skip`, `to_output`, `defer` | [Context API][context] |
98
+ | `prefetch`, `ssl_context`, TLS via environment | [Service Options][options] |
99
+ | `Service(...)` vs `Service.start(...)`, `close()` | [Starting & Stopping][lifecycle] |
100
+ | Generator handlers and `ctx.terminated` | [Continuous Mode][continuous] |
101
+ | `ctx.store` — what a node remembers past this message | [The Store][store] · [`ctx.store`][context-store] |
102
+ | `create_durable_callback`, `.for_(…)` | [Callbacks][callbacks] |
103
+ | `create_ui`, `ctx.render`, handler props | [Surfaces][surfaces] |
104
+ | `ctx.defer()` → `service.act()` | [Deferred Delivery][deferred] |
105
+ | Running locally against real tasks | [Dev Overlay][overlay] |
106
+ | `requence-service generate-types` | [Typing / CLI][typing] |
107
+
108
+ ### Starting tasks
109
+
110
+ | Topic | Page |
111
+ | --------------------------------------------------------- | ------------------------------- |
112
+ | Options, `task.sync`, abort, protect, `require_ack` | [Starting Tasks][starting] |
113
+ | Sync and async iteration, the update types | [Streaming Updates][streaming] |
114
+ | `TaskWatcher` across every task | [Watching Tasks][watching] |
115
+ | `get_task` | [Fetching & Recreating][fetch] |
116
+ | `requence-task generate-types` | [CLI][cli] |
117
+
118
+ `test/demo-service/surface_demo.py` and `test/demo-python/` in the Requence repository are
119
+ runnable examples.
120
+
121
+ [started]: https://docs.requence.cloud/implementation/getting-started/
122
+ [context]: https://docs.requence.cloud/implementation/context-api/
123
+ [context-store]: https://docs.requence.cloud/implementation/context-api/#ctxstoreprivatekey-binding--ctxstoresharedkey-binding
124
+ [options]: https://docs.requence.cloud/implementation/advanced/service-options/
125
+ [lifecycle]: https://docs.requence.cloud/implementation/advanced/
126
+ [continuous]: https://docs.requence.cloud/planning/continuous-mode/
127
+ [store]: https://docs.requence.cloud/planning/store/
128
+ [callbacks]: https://docs.requence.cloud/implementation/callbacks/
129
+ [surfaces]: https://docs.requence.cloud/implementation/surfaces/
130
+ [deferred]: https://docs.requence.cloud/implementation/advanced/deferred-delivery/
131
+ [overlay]: https://docs.requence.cloud/implementation/advanced/dev-overlay/
132
+ [typing]: https://docs.requence.cloud/implementation/typing-cli/
133
+ [starting]: https://docs.requence.cloud/execution/starting-tasks/
134
+ [streaming]: https://docs.requence.cloud/execution/streaming/
135
+ [watching]: https://docs.requence.cloud/execution/watching-tasks/
136
+ [fetch]: https://docs.requence.cloud/execution/managing-tasks/
137
+ [cli]: https://docs.requence.cloud/execution/cli/
@@ -0,0 +1,125 @@
1
+ # requence
2
+
3
+ The official Python SDK for the Requence platform. It covers both halves of the integration:
4
+
5
+ - **`requence.service`** — connect a Python service to Requence and process messages
6
+ - **`requence.task`** — start and monitor Requence tasks programmatically
7
+
8
+ > **This README is a getting-started guide.** The reference for both halves lives at
9
+ > **<https://docs.requence.cloud>** — every page has a **Python** tab, including the places
10
+ > where Python's answer differs from TypeScript's.
11
+
12
+ ## Requirements
13
+
14
+ Python 3.12 or later.
15
+
16
+ ## Installation
17
+
18
+ ```bash
19
+ pip install requence
20
+ ```
21
+
22
+ ## Authentication
23
+
24
+ Copy a service's access token from the **Services** list view in the Requence UI
25
+ (**Copy credentials**). A task needs a personal or scoped access token instead.
26
+
27
+ Tokens are resolved in this order:
28
+
29
+ 1. `access_token` passed to `Service()` / `Task()`
30
+ 2. `REQUENCE_SERVICE_ACCESS_TOKEN` / `REQUENCE_TASK_ACCESS_TOKEN`, then `REQUENCE_ACCESS_TOKEN`
31
+ 3. `requence.service_access_token` / `requence.task_access_token`, then `requence.access_token`
32
+ in `pyproject.toml`
33
+
34
+ ```bash
35
+ REQUENCE_SERVICE_ACCESS_TOKEN=your-token python main.py
36
+ ```
37
+
38
+ ## Your first service
39
+
40
+ Create the service in the Requence UI first — its input schema, configuration schema and
41
+ outputs. Then implement the version:
42
+
43
+ ```python
44
+ from requence.service import Service
45
+
46
+ def handler(ctx):
47
+ return {"message": f"Hello, {ctx.input['name']}!"}
48
+
49
+ Service("1.0.0", handler)
50
+ ```
51
+
52
+ > **`Service(...)` never returns.** It consumes on the calling thread, so there is no instance
53
+ > to call `act()` or `close()` on. Use `Service.start(...)` when you need either — it returns
54
+ > the instance once connected, on a daemon consume thread. See
55
+ > [Starting & Stopping][lifecycle].
56
+
57
+ Generate type stubs for `ctx.input`, `ctx.configuration` and `ctx.to_output()` from the schemas
58
+ you defined in the UI:
59
+
60
+ ```bash
61
+ requence-service generate-types
62
+ ```
63
+
64
+ ## Your first task
65
+
66
+ ```python
67
+ from requence.task import Task
68
+
69
+ task = Task(task_template="my-template", input={"name": "World"})
70
+ result = task.sync.result # blocks until the task completes
71
+
72
+ print(result["result"])
73
+ ```
74
+
75
+ `task.sync` holds the blocking accessors; `await task.result` and `async for update in
76
+ task.updates` are the async equivalents.
77
+
78
+ ## Where to read next
79
+
80
+ ### Writing a service
81
+
82
+ | Topic | Page |
83
+ | ----------------------------------------------------------------------- | ------------------------------------------------- |
84
+ | The full walkthrough | [Getting Started][started] |
85
+ | `ctx.input`, `ctx.debug`, `retry`, `abort`, `skip`, `to_output`, `defer` | [Context API][context] |
86
+ | `prefetch`, `ssl_context`, TLS via environment | [Service Options][options] |
87
+ | `Service(...)` vs `Service.start(...)`, `close()` | [Starting & Stopping][lifecycle] |
88
+ | Generator handlers and `ctx.terminated` | [Continuous Mode][continuous] |
89
+ | `ctx.store` — what a node remembers past this message | [The Store][store] · [`ctx.store`][context-store] |
90
+ | `create_durable_callback`, `.for_(…)` | [Callbacks][callbacks] |
91
+ | `create_ui`, `ctx.render`, handler props | [Surfaces][surfaces] |
92
+ | `ctx.defer()` → `service.act()` | [Deferred Delivery][deferred] |
93
+ | Running locally against real tasks | [Dev Overlay][overlay] |
94
+ | `requence-service generate-types` | [Typing / CLI][typing] |
95
+
96
+ ### Starting tasks
97
+
98
+ | Topic | Page |
99
+ | --------------------------------------------------------- | ------------------------------- |
100
+ | Options, `task.sync`, abort, protect, `require_ack` | [Starting Tasks][starting] |
101
+ | Sync and async iteration, the update types | [Streaming Updates][streaming] |
102
+ | `TaskWatcher` across every task | [Watching Tasks][watching] |
103
+ | `get_task` | [Fetching & Recreating][fetch] |
104
+ | `requence-task generate-types` | [CLI][cli] |
105
+
106
+ `test/demo-service/surface_demo.py` and `test/demo-python/` in the Requence repository are
107
+ runnable examples.
108
+
109
+ [started]: https://docs.requence.cloud/implementation/getting-started/
110
+ [context]: https://docs.requence.cloud/implementation/context-api/
111
+ [context-store]: https://docs.requence.cloud/implementation/context-api/#ctxstoreprivatekey-binding--ctxstoresharedkey-binding
112
+ [options]: https://docs.requence.cloud/implementation/advanced/service-options/
113
+ [lifecycle]: https://docs.requence.cloud/implementation/advanced/
114
+ [continuous]: https://docs.requence.cloud/planning/continuous-mode/
115
+ [store]: https://docs.requence.cloud/planning/store/
116
+ [callbacks]: https://docs.requence.cloud/implementation/callbacks/
117
+ [surfaces]: https://docs.requence.cloud/implementation/surfaces/
118
+ [deferred]: https://docs.requence.cloud/implementation/advanced/deferred-delivery/
119
+ [overlay]: https://docs.requence.cloud/implementation/advanced/dev-overlay/
120
+ [typing]: https://docs.requence.cloud/implementation/typing-cli/
121
+ [starting]: https://docs.requence.cloud/execution/starting-tasks/
122
+ [streaming]: https://docs.requence.cloud/execution/streaming/
123
+ [watching]: https://docs.requence.cloud/execution/watching-tasks/
124
+ [fetch]: https://docs.requence.cloud/execution/managing-tasks/
125
+ [cli]: https://docs.requence.cloud/execution/cli/
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "requence"
7
- version = "0.8.1.dev63"
7
+ version = "0.8.1.dev67"
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,5 +1,6 @@
1
1
  from typing import TYPE_CHECKING, Any, Optional, Callable, cast
2
2
  from .exceptions import RetryException, AbortException, SkipException
3
+ from .store import Store
3
4
  from .utils import OutputValue
4
5
  from .wire import DEFAULT_SURFACE_ID
5
6
  import threading
@@ -41,7 +42,8 @@ class Context[I, C]:
41
42
  on_log: Callable[[str, Any], None],
42
43
  on_defer: Callable[[Optional[str]], str],
43
44
  terminated: threading.Event,
44
- on_render: Optional[Callable[["RequenceUI[Any]", Any, str], None]] = None
45
+ on_render: Optional[Callable[["RequenceUI[Any]", Any, str], None]] = None,
46
+ store: Optional[Store] = None
45
47
  ):
46
48
 
47
49
  self.task_id = task_id
@@ -51,6 +53,16 @@ class Context[I, C]:
51
53
  self.__on_defer = on_defer
52
54
  self.__on_render = on_render
53
55
  self.debug = Debug(on_log)
56
+ # What this node remembers past the end of this message, and past the
57
+ # end of this task (#211). Always present, so `context.store` is never
58
+ # the thing that is missing — a dispatch carrying no capability says so
59
+ # when a slot is read or written, not here.
60
+ #
61
+ # `store=None` only reaches a context built outside a dispatch (tests);
62
+ # such a store has nothing to address and says exactly that.
63
+ self.store = store if store is not None else Store(
64
+ url=None, signature=None, task_id=task_id, node_id=None
65
+ )
54
66
 
55
67
  def retry(self, delay: Optional[int] = None):
56
68
  raise RetryException(delay)
@@ -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):
@@ -21,10 +21,26 @@ class TaskOptions(TypedDict, total=False):
21
21
  # URLs: claim-check offload threshold and RequenceFile/RequenceStream cap.
22
22
  maxPayloadSize: Optional[int]
23
23
  maxFileSize: Optional[int]
24
+ # The store capability (#211), copied onto every dispatch by the operator,
25
+ # which reads neither field. The URL is TOLD rather than derived — unlike a
26
+ # file reference, a store call carries no URL of its own — and it is the
27
+ # PUBLIC one, because an off-overlay service is a supported deployment.
28
+ storeUrl: Optional[str]
29
+ storeSignature: Optional[str]
24
30
 
25
31
  class Payload(TypedDict, total=True):
26
32
  input: Any
27
33
  configuration: Any
34
+ # Which node of the graph this dispatch is for — the address a durable
35
+ # callback reference carries out with it (#150). NotRequired because a
36
+ # dispatch minted before it existed carries none, and that message simply
37
+ # cannot emit one.
38
+ nodeId: NotRequired[str]
39
+ # Set only when this dispatch is a configuration-function evaluation (#224).
40
+ # `nodeId` is then the HOST node's, and a `private` store slot addresses that
41
+ # node's configuration box rather than the host service's own. Not spelled
42
+ # `configuration`: that key above is this envelope's configuration VALUE.
43
+ configurationEval: NotRequired[bool]
28
44
  options: TaskOptions
29
45
 
30
46
  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