requence 0.8.1.dev64__tar.gz → 0.8.1.dev72__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 (81) hide show
  1. requence-0.8.1.dev72/PKG-INFO +137 -0
  2. requence-0.8.1.dev72/README.md +125 -0
  3. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/pyproject.toml +1 -1
  4. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/client_properties.py +45 -3
  5. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/context.py +13 -1
  6. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/internal_types.py +11 -0
  7. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/service/__init__.py +105 -20
  8. requence-0.8.1.dev72/requence/store.py +354 -0
  9. requence-0.8.1.dev72/requence.egg-info/PKG-INFO +137 -0
  10. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence.egg-info/SOURCES.txt +2 -0
  11. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/tests/test_client_properties.py +108 -16
  12. requence-0.8.1.dev72/tests/test_store_parity.py +377 -0
  13. requence-0.8.1.dev64/PKG-INFO +0 -972
  14. requence-0.8.1.dev64/README.md +0 -960
  15. requence-0.8.1.dev64/requence.egg-info/PKG-INFO +0 -972
  16. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/MANIFEST.in +0 -0
  17. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/__init__.py +0 -0
  18. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/callbacks/__init__.py +0 -0
  19. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/callbacks/context.py +0 -0
  20. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/callbacks/handler.py +0 -0
  21. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/exceptions.py +0 -0
  22. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/__init__.py +0 -0
  23. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/errors.py +0 -0
  24. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/handlers/__init__.py +0 -0
  25. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/handlers/claim_check_handler.py +0 -0
  26. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/handlers/context.py +0 -0
  27. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/handlers/file_handler.py +0 -0
  28. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/handlers/stream_handler.py +0 -0
  29. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/pending_uploads.py +0 -0
  30. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/requence_file.py +0 -0
  31. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/requence_stream.py +0 -0
  32. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/sanitize_log_data.py +0 -0
  33. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/stream_framing.py +0 -0
  34. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/files/transport.py +0 -0
  35. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/logger.py +0 -0
  36. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/obfuscase.py +0 -0
  37. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/py.typed +0 -0
  38. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/reachable.py +0 -0
  39. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/requence_callback.py +0 -0
  40. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/requence_file.py +0 -0
  41. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/requence_stream.py +0 -0
  42. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/service/boundary.py +0 -0
  43. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/service/callback_growth.py +0 -0
  44. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/service/cli.py +0 -0
  45. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/service/durable_callback.py +0 -0
  46. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/service/surface_handler.py +0 -0
  47. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/service/transformer.py +0 -0
  48. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/service/types.py +0 -0
  49. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/service/ui.py +0 -0
  50. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/service/ui_watch.py +0 -0
  51. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/__init__.py +0 -0
  52. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/abort_task.py +0 -0
  53. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/ack_task.py +0 -0
  54. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/cli.py +0 -0
  55. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/get_task.py +0 -0
  56. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/ingress.py +0 -0
  57. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/protect_task.py +0 -0
  58. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/task.py +0 -0
  59. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/task_watcher.py +0 -0
  60. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/types.py +0 -0
  61. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/updates.py +0 -0
  62. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/task/utils.py +0 -0
  63. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/transformer/__init__.py +0 -0
  64. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/transformer/context.py +0 -0
  65. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/transformer/errors.py +0 -0
  66. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/transformer/guards.py +0 -0
  67. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/transformer/message_handler.py +0 -0
  68. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/transformer/transform.py +0 -0
  69. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/transformer/value_handler.py +0 -0
  70. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/transformer/walk.py +0 -0
  71. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/utils.py +0 -0
  72. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/wire.py +0 -0
  73. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence/wire_codec.py +0 -0
  74. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence.egg-info/dependency_links.txt +0 -0
  75. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence.egg-info/entry_points.txt +0 -0
  76. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence.egg-info/requires.txt +0 -0
  77. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/requence.egg-info/top_level.txt +0 -0
  78. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/setup.cfg +0 -0
  79. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/tests/test_logger.py +0 -0
  80. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/tests/test_wire.py +0 -0
  81. {requence-0.8.1.dev64 → requence-0.8.1.dev72}/tests/test_wire_codec.py +0 -0
@@ -0,0 +1,137 @@
1
+ Metadata-Version: 2.4
2
+ Name: requence
3
+ Version: 0.8.1.dev72
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.dev64"
7
+ version = "0.8.1.dev72"
8
8
  description = "Requence Service"
9
9
  readme = { file = "README.md", content-type = "text/markdown" }
10
10
  authors = [{ name = "Torsten Blindert" }]
@@ -41,6 +41,16 @@ CLIENT_PROPERTY_KEYS = {
41
41
  # Marks a developer's local dev-overlay connection. Only the marker travels,
42
42
  # never the devKey (which is an access-token value).
43
43
  "devOverlay": "requence_dev_overlay",
44
+ # WHICH PROCESS this is. Not a new id: it is the same per-connection uuid the
45
+ # SDK already stamps on every publish (and names its backchannel queue with),
46
+ # announced here so a fleet row and a node run can be joined on it. This SDK
47
+ # mints a fresh one per broker connection, where the TS SDK keeps its id
48
+ # across a reconnect — a deliberate difference, not a bug.
49
+ "connectionId": "requence_connection_id",
50
+ # How many task slots this process has: the consumer prefetch of its DISPATCH
51
+ # channel. The surface-handler and durable-callback channels each get their
52
+ # own budget of the same number, so this is NOT the replica's whole capacity.
53
+ "prefetch": "requence_prefetch",
44
54
  }
45
55
 
46
56
  # The name is author-controlled text and the whole client-properties table
@@ -69,19 +79,29 @@ def build_service_client_properties(
69
79
  *,
70
80
  lib_version: str,
71
81
  service_version: str,
82
+ connection_id: str,
83
+ prefetch: int,
72
84
  name: Optional[str] = None,
73
85
  dev_overlay: bool = False,
74
86
  capabilities: Optional[Iterable[str]] = None,
75
87
  ) -> Dict[str, str]:
76
88
  """Build the properties handed to pika on connect (and therefore on every
77
89
  reconnect, since the connection parameters are reused). Absent optional
78
- fields are OMITTED, never sent blank."""
90
+ fields are OMITTED, never sent blank.
91
+
92
+ ``connection_id`` and ``prefetch`` are REQUIRED, mirroring the TS contract:
93
+ both are known at connect time in every SDK, so a forgetful one should fail
94
+ loudly rather than announce a replica nothing can join."""
79
95
  if capabilities is None:
80
96
  capabilities = SERVICE_WIRE_CAPABILITIES
81
97
 
82
98
  properties: Dict[str, str] = {
83
99
  CLIENT_PROPERTY_KEYS["libVersion"]: lib_version,
84
100
  CLIENT_PROPERTY_KEYS["serviceVersion"]: service_version,
101
+ CLIENT_PROPERTY_KEYS["connectionId"]: connection_id,
102
+ # Stringified, like every other value here: the table is flat strings on
103
+ # purpose. The read side (ui/backend) decides whether it is usable.
104
+ CLIENT_PROPERTY_KEYS["prefetch"]: str(prefetch),
85
105
  CLIENT_PROPERTY_KEYS["capabilities"]: ",".join(capabilities)[
86
106
  :MAX_CAPABILITIES_LENGTH
87
107
  ],
@@ -99,7 +119,7 @@ def build_service_client_properties(
99
119
 
100
120
  # ─── The second announcement: per-run identity on the begin message ──────────
101
121
  #
102
- # The same three values as above, sent again on the ``begin`` publish, because
122
+ # Mostly the same values as above, sent again on the ``begin`` publish, because
103
123
  # they answer a DIFFERENT question: the client properties say "can this fleet
104
124
  # decode msgpack?" (live, folded to the minimum, available before dispatch),
105
125
  # these say "which build ran THIS node?" (exact, frozen into the NODE_START
@@ -111,22 +131,44 @@ IDENTITY_HEADER_KEYS = {
111
131
  "libVersion": "libVersion",
112
132
  "name": "serviceName",
113
133
  "capabilities": "capabilities",
134
+ # READ-ONLY, and the only asymmetry in this dict: every other key here is
135
+ # both built and read, but ``build_service_identity_headers`` does NOT emit
136
+ # this one. The base publish header block already stamps ``connectionId`` on
137
+ # EVERY message, begin included, so emitting it again would write the same
138
+ # value twice into one header table. It is listed here so ui/backend's reader
139
+ # picks it up — and so the key-name parity test covers the name.
140
+ "connectionId": "connectionId",
141
+ # Does THIS run occupy one of the consumer's dispatch prefetch slots — i.e.
142
+ # does its message stay unacked while the work runs? Per run, not per
143
+ # replica. Emitted by the builder (unlike ``connectionId``), because it is
144
+ # new.
145
+ "holdsSlot": "holdsSlot",
114
146
  }
115
147
 
116
148
 
117
149
  def build_service_identity_headers(
118
150
  *,
119
151
  lib_version: str,
152
+ holds_slot: bool,
120
153
  name: Optional[str] = None,
121
154
  capabilities: Optional[Iterable[str]] = None,
122
155
  ) -> Dict[str, str]:
123
156
  """Headers the service stamps on its own ``begin`` publish, built from this
124
- process's own constants — nothing is looked up, so nothing can be stale."""
157
+ process's own constants — nothing is looked up, so nothing can be stale.
158
+
159
+ ``holds_slot`` is ``not (is_generator and mode == 'CONTINUOUS')`` at every
160
+ call site: that one combination acks immediately and frees its slot, every
161
+ other stays unacked until the work is done."""
125
162
  if capabilities is None:
126
163
  capabilities = SERVICE_WIRE_CAPABILITIES
127
164
 
128
165
  headers: Dict[str, str] = {
129
166
  IDENTITY_HEADER_KEYS["libVersion"]: lib_version,
167
+ # ALWAYS sent, breaking this module's "absent optional fields are
168
+ # OMITTED" rule on purpose: omitting False would make it
169
+ # indistinguishable from an SDK too old to report, and those two answers
170
+ # are not the same.
171
+ IDENTITY_HEADER_KEYS["holdsSlot"]: "1" if holds_slot else "0",
130
172
  IDENTITY_HEADER_KEYS["capabilities"]: ",".join(capabilities)[
131
173
  :MAX_CAPABILITIES_LENGTH
132
174
  ],
@@ -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)
@@ -21,6 +21,12 @@ 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
@@ -30,6 +36,11 @@ class Payload(TypedDict, total=True):
30
36
  # dispatch minted before it existed carries none, and that message simply
31
37
  # cannot emit one.
32
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]
33
44
  options: TaskOptions
34
45
 
35
46
  class ActorApi(TypedDict):
@@ -9,6 +9,7 @@ from ..client_properties import (
9
9
  unsupported_capabilities,
10
10
  )
11
11
  from ..context import Context
12
+ from ..store import Store
12
13
  from ..logger import logger
13
14
  from ..utils import is_valid_uuid, libVersion, OutputValue
14
15
  from ..exceptions import (
@@ -66,6 +67,22 @@ from .durable_callback import (
66
67
  )
67
68
  from .ui import RequenceUI, create_ui
68
69
  from .ui_watch import UIWatchListener, find_ui_by_id, watch_ui_rebuilds
70
+ # The store's handle type and its named refusals (#211). `StoreSlot` is exported
71
+ # because it is how an author pins the value type — Python has no call-site type
72
+ # argument, so the annotation is the only place to say it:
73
+ #
74
+ # cursor: StoreSlot[int] = context.store.private('lastUid', 'taskTemplate')
75
+ from ..store import (
76
+ StoreAddressFullException,
77
+ StoreException,
78
+ StoreRequestException,
79
+ StoreSlot,
80
+ StoreTaskNotAllowedException,
81
+ StoreUnauthorizedException,
82
+ StoreUnavailableException,
83
+ StoreValueNotStorableException,
84
+ StoreValueTooLargeException,
85
+ )
69
86
 
70
87
  __all__ = [
71
88
  'Service',
@@ -77,6 +94,15 @@ __all__ = [
77
94
  'create_durable_callback',
78
95
  'RequenceUI',
79
96
  'create_ui',
97
+ 'StoreSlot',
98
+ 'StoreException',
99
+ 'StoreUnavailableException',
100
+ 'StoreRequestException',
101
+ 'StoreUnauthorizedException',
102
+ 'StoreTaskNotAllowedException',
103
+ 'StoreAddressFullException',
104
+ 'StoreValueTooLargeException',
105
+ 'StoreValueNotStorableException',
80
106
  ]
81
107
 
82
108
  MessageHandlerFunction = Callable[[Context[Any, Any]], Any | None]
@@ -346,16 +372,11 @@ class Service:
346
372
  if heartbeat_interval is not None:
347
373
  parameters.heartbeat = heartbeat_interval
348
374
 
349
- # Who we are, what we run, what we can decode — declared in the AMQP
350
- # connection frame so ui/backend knows it BEFORE the first dispatch. pika
351
- # merges these over its own defaults, and the parameters are reused on
352
- # every reconnect, so the announcement re-lands automatically.
353
- parameters.client_properties = build_service_client_properties(
354
- lib_version=libVersion,
355
- service_version=version,
356
- name=service_config.get("name"),
357
- dev_overlay=dev_overlay is not None,
358
- )
375
+ # The client properties are NOT built here: they carry this connection's
376
+ # own uuid, and `__connection_id` is minted per broker connection (see
377
+ # `__connect_and_consume`), so a table frozen at configure time would
378
+ # announce the id of a connection that no longer exists. It is rebuilt
379
+ # immediately before every connect instead.
359
380
 
360
381
  if not parameters.credentials:
361
382
  raise ValueError("Url connection string needs a username")
@@ -363,8 +384,8 @@ class Service:
363
384
  self.__parameters = parameters
364
385
  self.__version = version
365
386
  # Author-chosen debugging label. Announced twice — in the client
366
- # properties above (fleet view) and on every begin publish (per-run
367
- # identity) — from this one value, so the two can never disagree.
387
+ # properties (fleet view) and on every begin publish (per-run identity)
388
+ # — from this one value, so the two can never disagree.
368
389
  self.__name = service_config.get("name")
369
390
  self.__prefetch = prefetch
370
391
  self.__dev_overlay = dev_overlay
@@ -374,12 +395,16 @@ class Service:
374
395
  f"{self.__base_queue}-dev-overlay-{dev_overlay}" if dev_overlay else self.__base_queue
375
396
  )
376
397
  self.__on_message_callback = on_message_callback
377
- # A property of the HANDLER, decided once: only a generator handler can
378
- # hold a registration past the call that made it. Same rule for render
379
- # props — a function written inline at `context.render` dies when a
380
- # non-generator handler returns, so it is refused rather than published
381
- # (see `__handle_message`).
382
- self.__can_register_callbacks = inspect.isgeneratorfunction(on_message_callback)
398
+ # A property of the HANDLER, decided once. Two independent things are
399
+ # decided by it, so it is held under its own name rather than either of
400
+ # them borrowing the other's: whether a callback registration can outlive
401
+ # the call that made it, and whether a CONTINUOUS run holds a task slot.
402
+ self.__is_generator_handler = inspect.isgeneratorfunction(on_message_callback)
403
+ # Only a generator handler can hold a registration past the call that
404
+ # made it. Same rule for render props — a function written inline at
405
+ # `context.render` dies when a non-generator handler returns, so it is
406
+ # refused rather than published (see `__handle_message`).
407
+ self.__can_register_callbacks = self.__is_generator_handler
383
408
 
384
409
  # The dev session this connection belongs to (#108), or '' outside dev
385
410
  # mode.
@@ -477,9 +502,28 @@ class Service:
477
502
  """Open a connection, (re)declare the topology, and block in
478
503
  start_consuming until the connection drops (raises) or close() stops it
479
504
  (returns normally)."""
505
+ # Minted BEFORE the connect, because the announcement carries it. This
506
+ # SDK gives every broker connection a fresh id (the TS SDK keeps one
507
+ # across a reconnect) — accepted, not aligned: both give a correct join
508
+ # at any instant, and in-flight work does not survive a reconnect either
509
+ # way, so an id that outlived the connection would buy nothing.
510
+ self.__connection_id = str(uuid4())
511
+
512
+ # Who we are, what we run, what we can decode, WHICH process this is and
513
+ # how many task slots it has — declared in the AMQP connection frame so
514
+ # ui/backend knows it BEFORE the first dispatch. Rebuilt per connect, not
515
+ # once at configure time, precisely because the id above is.
516
+ self.__parameters.client_properties = build_service_client_properties(
517
+ lib_version=libVersion,
518
+ service_version=self.__version,
519
+ connection_id=self.__connection_id,
520
+ prefetch=self.__prefetch,
521
+ name=self.__name,
522
+ dev_overlay=self.__dev_overlay is not None,
523
+ )
524
+
480
525
  connection = pika.BlockingConnection(self.__parameters)
481
526
 
482
- self.__connection_id = str(uuid4())
483
527
  backchannel_queue = f"{self.__base_queue}-backchannel-{self.__connection_id}"
484
528
 
485
529
  channel = connection.channel()
@@ -591,6 +635,11 @@ class Service:
591
635
  )
592
636
  )
593
637
 
638
+ # Mirroring the loss logged in `__run`: without this, a recovery is
639
+ # completely silent and indistinguishable from a hang. Logged before the
640
+ # flag is set, so the initial connect stays quiet.
641
+ if self.__ever_connected:
642
+ logger.info("Requence AMQP reconnected")
594
643
  self.__ever_connected = True
595
644
  # Set BEFORE the blocking consume: everything a caller of `start()` needs —
596
645
  # the connection, both channels, the topology — is in place, and the next
@@ -623,6 +672,10 @@ class Service:
623
672
  outage it exists for."""
624
673
  backoff = 1.0
625
674
  while not self.__closing:
675
+ # `__generation` only advances on a connection that reached the
676
+ # consume, so comparing it after the attempt says whether this
677
+ # attempt got a live connection or merely failed to make one.
678
+ generation = self.__generation
626
679
  try:
627
680
  self.__connect_and_consume()
628
681
  return # start_consuming returned normally: close() stopped us.
@@ -643,6 +696,14 @@ class Service:
643
696
 
644
697
  if self.__closing:
645
698
  return
699
+ # Backoff exists to space out attempts against a broker that is down,
700
+ # so it belongs to a run of consecutive FAILED connects. An attempt
701
+ # that connected and then lost the connection hours later starts a new
702
+ # outage: without this reset it would inherit the previous outage's
703
+ # wait and sit out up to 30s before a retry that would have succeeded
704
+ # immediately.
705
+ if self.__generation != generation:
706
+ backoff = 1.0
646
707
  time.sleep(min(backoff, 30.0) + random.uniform(0.0, 1.0))
647
708
  backoff = min(backoff * 2.0, 30.0)
648
709
 
@@ -1296,6 +1357,12 @@ class Service:
1296
1357
  # minted before it existed, which then simply cannot emit one, and the
1297
1358
  # callback handler says exactly that.
1298
1359
  node_id = payload.get("nodeId")
1360
+ # Set only when this dispatch is a configuration-function evaluation
1361
+ # (#224). `nodeId` is then the HOST node's — the node being
1362
+ # configured — and the store composes `private` slots into that
1363
+ # node's configuration box. Not spelled `configuration`: that key is
1364
+ # already this envelope's configuration VALUE.
1365
+ configuration_eval = payload.get("configurationEval") is True
1299
1366
 
1300
1367
  deferred = False
1301
1368
  deferred_reason: str | None = None
@@ -1486,7 +1553,19 @@ class Service:
1486
1553
  on_log=on_log,
1487
1554
  on_defer=on_defer,
1488
1555
  terminated=terminated,
1489
- on_render=lambda ui, props, surface_id: on_render(ui, props, surface_id)
1556
+ on_render=lambda ui, props, surface_id: on_render(ui, props, surface_id),
1557
+ # The whole of what a node needs to address a slot (#211): the
1558
+ # two opaque fields ui/backend minted for this tree, plus the
1559
+ # two ids this dispatch already carries. The service composes no
1560
+ # address and holds no store password — the store builds the
1561
+ # address from the capability.
1562
+ store=Store(
1563
+ url=options.get("storeUrl"),
1564
+ signature=options.get("storeSignature"),
1565
+ task_id=task_id,
1566
+ node_id=node_id,
1567
+ configuration=configuration_eval,
1568
+ ),
1490
1569
  )
1491
1570
 
1492
1571
  # The one stamp per node execution: this build, this box. It becomes
@@ -1497,6 +1576,12 @@ class Service:
1497
1576
  **build_service_identity_headers(
1498
1577
  lib_version=libVersion,
1499
1578
  name=self.__name,
1579
+ # Read the ack decision below: a CONTINUOUS generator acks
1580
+ # straight away and frees its slot, so its run holds none.
1581
+ # Every other combination stays unacked until the work is
1582
+ # done. ui/backend cannot derive this — it knows the mode
1583
+ # from the node but not whether the author wrote a generator.
1584
+ holds_slot=not (self.__is_generator_handler and mode == 'CONTINUOUS'),
1500
1585
  ),
1501
1586
  })
1502
1587