requence 0.7.1__tar.gz → 0.8.1.dev55__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.7.1 → requence-0.8.1.dev55}/PKG-INFO +39 -3
- requence-0.7.1/requence.egg-info/PKG-INFO → requence-0.8.1.dev55/README.md +37 -14
- {requence-0.7.1 → requence-0.8.1.dev55}/pyproject.toml +12 -1
- requence-0.8.1.dev55/requence/callbacks/__init__.py +11 -0
- requence-0.8.1.dev55/requence/callbacks/context.py +25 -0
- requence-0.8.1.dev55/requence/callbacks/handler.py +56 -0
- requence-0.8.1.dev55/requence/client_properties.py +211 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/context.py +15 -22
- requence-0.8.1.dev55/requence/exceptions.py +50 -0
- requence-0.8.1.dev55/requence/files/__init__.py +39 -0
- requence-0.8.1.dev55/requence/files/errors.py +11 -0
- requence-0.8.1.dev55/requence/files/handlers/__init__.py +9 -0
- requence-0.8.1.dev55/requence/files/handlers/claim_check_handler.py +177 -0
- requence-0.8.1.dev55/requence/files/handlers/context.py +73 -0
- requence-0.8.1.dev55/requence/files/handlers/file_handler.py +94 -0
- requence-0.8.1.dev55/requence/files/handlers/stream_handler.py +134 -0
- requence-0.8.1.dev55/requence/files/pending_uploads.py +41 -0
- requence-0.8.1.dev55/requence/files/requence_file.py +98 -0
- requence-0.8.1.dev55/requence/files/requence_stream.py +89 -0
- requence-0.8.1.dev55/requence/files/sanitize_log_data.py +32 -0
- requence-0.8.1.dev55/requence/files/stream_framing.py +81 -0
- requence-0.8.1.dev55/requence/files/transport.py +172 -0
- requence-0.8.1.dev55/requence/internal_types.py +33 -0
- requence-0.8.1.dev55/requence/reachable.py +40 -0
- requence-0.8.1.dev55/requence/requence_file.py +7 -0
- requence-0.8.1.dev55/requence/requence_stream.py +7 -0
- requence-0.8.1.dev55/requence/service/__init__.py +927 -0
- requence-0.8.1.dev55/requence/service/boundary.py +240 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/service/cli.py +10 -4
- requence-0.8.1.dev55/requence/service/transformer.py +21 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/__init__.py +2 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/abort_task.py +2 -3
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/ack_task.py +4 -4
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/cli.py +11 -5
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/get_task.py +7 -8
- requence-0.8.1.dev55/requence/task/ingress.py +94 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/protect_task.py +2 -3
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/task.py +80 -46
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/task_watcher.py +15 -11
- requence-0.8.1.dev55/requence/task/utils.py +38 -0
- requence-0.8.1.dev55/requence/transformer/__init__.py +35 -0
- requence-0.8.1.dev55/requence/transformer/context.py +43 -0
- requence-0.8.1.dev55/requence/transformer/errors.py +31 -0
- requence-0.8.1.dev55/requence/transformer/guards.py +34 -0
- requence-0.8.1.dev55/requence/transformer/message_handler.py +41 -0
- requence-0.8.1.dev55/requence/transformer/transform.py +169 -0
- requence-0.8.1.dev55/requence/transformer/value_handler.py +39 -0
- requence-0.8.1.dev55/requence/transformer/walk.py +60 -0
- requence-0.8.1.dev55/requence/utils.py +24 -0
- requence-0.8.1.dev55/requence/wire.py +128 -0
- requence-0.8.1.dev55/requence/wire_codec.py +169 -0
- requence-0.7.1/README.md → requence-0.8.1.dev55/requence.egg-info/PKG-INFO +50 -2
- requence-0.8.1.dev55/requence.egg-info/SOURCES.txt +67 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence.egg-info/requires.txt +1 -0
- requence-0.8.1.dev55/tests/test_client_properties.py +276 -0
- requence-0.8.1.dev55/tests/test_wire.py +109 -0
- requence-0.8.1.dev55/tests/test_wire_codec.py +233 -0
- requence-0.7.1/requence/exceptions.py +0 -20
- requence-0.7.1/requence/internal_types.py +0 -27
- requence-0.7.1/requence/requence_file.py +0 -61
- requence-0.7.1/requence/requence_stream.py +0 -52
- requence-0.7.1/requence/service/__init__.py +0 -510
- requence-0.7.1/requence/task/utils.py +0 -58
- requence-0.7.1/requence/utils.py +0 -194
- requence-0.7.1/requence.egg-info/SOURCES.txt +0 -33
- {requence-0.7.1 → requence-0.8.1.dev55}/MANIFEST.in +0 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/__init__.py +0 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/obfuscase.py +0 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/py.typed +0 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/requence_callback.py +0 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/service/types.py +0 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/types.py +0 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/updates.py +0 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence.egg-info/dependency_links.txt +0 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence.egg-info/entry_points.txt +0 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/requence.egg-info/top_level.txt +0 -0
- {requence-0.7.1 → requence-0.8.1.dev55}/setup.cfg +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: requence
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.8.1.dev55
|
|
4
4
|
Summary: Requence Service
|
|
5
5
|
Author: Torsten Blindert
|
|
6
6
|
Requires-Python: >=3.12
|
|
@@ -9,6 +9,7 @@ Requires-Dist: pika>=1.3.2
|
|
|
9
9
|
Requires-Dist: requests>=2.32.2
|
|
10
10
|
Requires-Dist: colorama>=0.4.6
|
|
11
11
|
Requires-Dist: sseclient-py>=1.8.0
|
|
12
|
+
Requires-Dist: msgpack>=1.0.5
|
|
12
13
|
|
|
13
14
|
# requence
|
|
14
15
|
|
|
@@ -81,6 +82,16 @@ Service(
|
|
|
81
82
|
)
|
|
82
83
|
```
|
|
83
84
|
|
|
85
|
+
For `amqps://` connections, TLS settings can also be overridden with
|
|
86
|
+
environment variables (a **fallback** — a passed `ssl_context` takes
|
|
87
|
+
precedence):
|
|
88
|
+
|
|
89
|
+
| Variable | Effect |
|
|
90
|
+
| --------------------- | -------------------------------------------------------------------- |
|
|
91
|
+
| `CA` | Inline PEM certificate(s) to trust as the CA. |
|
|
92
|
+
| `CA_FILE` | Path to a PEM file to trust as the CA (`CA` wins when both are set). |
|
|
93
|
+
| `REJECT_UNAUTHORIZED` | Set to `false`/`0`/`no` to disable certificate verification. |
|
|
94
|
+
|
|
84
95
|
### Dev Overlay
|
|
85
96
|
|
|
86
97
|
When developing locally alongside a deployed service, pass a **dev token** (your personal access token) so Requence routes only your own tasks to the local instance instead of the production pool:
|
|
@@ -288,7 +299,32 @@ The package installs a `requence-service` CLI that generates Python type stubs f
|
|
|
288
299
|
requence-service generate-types
|
|
289
300
|
```
|
|
290
301
|
|
|
291
|
-
Type stubs are written to `typings/requence/service/`.
|
|
302
|
+
Type stubs are written to `typings/requence/service/`. Pylance and pyright read a top-level `typings/` directory automatically, so no extra configuration is needed. (If you pass a custom `--outdir`, point your type checker's stub path at it — e.g. `python.analysis.stubPath` for Pylance.)
|
|
303
|
+
|
|
304
|
+
### Using the generated types
|
|
305
|
+
|
|
306
|
+
Unlike TypeScript — where the `createService` callback is typed automatically — a Python type checker **cannot** infer the type of a named handler's parameter from the `Service(...)` call. Import the type for your service version and annotate the handler's `ctx` parameter:
|
|
307
|
+
|
|
308
|
+
```python
|
|
309
|
+
from requence.service import Service
|
|
310
|
+
from requence.service.types import some_types # one class per service version
|
|
311
|
+
|
|
312
|
+
def handler(ctx: some_types.context) -> some_types.output:
|
|
313
|
+
name = ctx.input["name"] # typed from the version's input schema
|
|
314
|
+
return {"number": 10} # checked against the version's output schema
|
|
315
|
+
|
|
316
|
+
Service("some-types", handler) # the version string is validated too
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
The class name is your service version with every character that isn't a letter or digit replaced by `_`, and a leading `v` added if it starts with a digit — e.g. `some-types` → `some_types`, `1.2.3` → `v1_2_3`.
|
|
320
|
+
|
|
321
|
+
- **`ctx: <version>.context`** types `ctx.input`, `ctx.configuration`, and `ctx.to_output()`.
|
|
322
|
+
- **`-> <version>.output`** is required when you `return` an output dict literal directly (without it the checker infers a plain `dict` that won't match the output schema). You can omit it if you return through `ctx.to_output(...)`, whose return type already matches.
|
|
323
|
+
- For a trivial one-liner you can skip both the import and the annotation with a lambda, which the type checker types contextually:
|
|
324
|
+
|
|
325
|
+
```python
|
|
326
|
+
Service("some-types", lambda ctx: {"number": 10}) # ctx is fully typed
|
|
327
|
+
```
|
|
292
328
|
|
|
293
329
|
### Options
|
|
294
330
|
|
|
@@ -578,7 +614,7 @@ The package installs a `requence-task` CLI that generates Python type stubs from
|
|
|
578
614
|
requence-task generate-types
|
|
579
615
|
```
|
|
580
616
|
|
|
581
|
-
Type stubs are written to `typings/requence/task
|
|
617
|
+
Type stubs are written to `typings/requence/task/`, giving you type hints for task inputs and results. As with the service stubs, Pylance and pyright read a top-level `typings/` directory automatically (point your stub path at a custom `--outdir` otherwise).
|
|
582
618
|
|
|
583
619
|
### Options
|
|
584
620
|
|
|
@@ -1,15 +1,3 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: requence
|
|
3
|
-
Version: 0.7.1
|
|
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: colorama>=0.4.6
|
|
11
|
-
Requires-Dist: sseclient-py>=1.8.0
|
|
12
|
-
|
|
13
1
|
# requence
|
|
14
2
|
|
|
15
3
|
The official Python SDK for the Requence platform. This package covers both halves of the integration:
|
|
@@ -81,6 +69,16 @@ Service(
|
|
|
81
69
|
)
|
|
82
70
|
```
|
|
83
71
|
|
|
72
|
+
For `amqps://` connections, TLS settings can also be overridden with
|
|
73
|
+
environment variables (a **fallback** — a passed `ssl_context` takes
|
|
74
|
+
precedence):
|
|
75
|
+
|
|
76
|
+
| Variable | Effect |
|
|
77
|
+
| --------------------- | -------------------------------------------------------------------- |
|
|
78
|
+
| `CA` | Inline PEM certificate(s) to trust as the CA. |
|
|
79
|
+
| `CA_FILE` | Path to a PEM file to trust as the CA (`CA` wins when both are set). |
|
|
80
|
+
| `REJECT_UNAUTHORIZED` | Set to `false`/`0`/`no` to disable certificate verification. |
|
|
81
|
+
|
|
84
82
|
### Dev Overlay
|
|
85
83
|
|
|
86
84
|
When developing locally alongside a deployed service, pass a **dev token** (your personal access token) so Requence routes only your own tasks to the local instance instead of the production pool:
|
|
@@ -288,7 +286,32 @@ The package installs a `requence-service` CLI that generates Python type stubs f
|
|
|
288
286
|
requence-service generate-types
|
|
289
287
|
```
|
|
290
288
|
|
|
291
|
-
Type stubs are written to `typings/requence/service/`.
|
|
289
|
+
Type stubs are written to `typings/requence/service/`. Pylance and pyright read a top-level `typings/` directory automatically, so no extra configuration is needed. (If you pass a custom `--outdir`, point your type checker's stub path at it — e.g. `python.analysis.stubPath` for Pylance.)
|
|
290
|
+
|
|
291
|
+
### Using the generated types
|
|
292
|
+
|
|
293
|
+
Unlike TypeScript — where the `createService` callback is typed automatically — a Python type checker **cannot** infer the type of a named handler's parameter from the `Service(...)` call. Import the type for your service version and annotate the handler's `ctx` parameter:
|
|
294
|
+
|
|
295
|
+
```python
|
|
296
|
+
from requence.service import Service
|
|
297
|
+
from requence.service.types import some_types # one class per service version
|
|
298
|
+
|
|
299
|
+
def handler(ctx: some_types.context) -> some_types.output:
|
|
300
|
+
name = ctx.input["name"] # typed from the version's input schema
|
|
301
|
+
return {"number": 10} # checked against the version's output schema
|
|
302
|
+
|
|
303
|
+
Service("some-types", handler) # the version string is validated too
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
The class name is your service version with every character that isn't a letter or digit replaced by `_`, and a leading `v` added if it starts with a digit — e.g. `some-types` → `some_types`, `1.2.3` → `v1_2_3`.
|
|
307
|
+
|
|
308
|
+
- **`ctx: <version>.context`** types `ctx.input`, `ctx.configuration`, and `ctx.to_output()`.
|
|
309
|
+
- **`-> <version>.output`** is required when you `return` an output dict literal directly (without it the checker infers a plain `dict` that won't match the output schema). You can omit it if you return through `ctx.to_output(...)`, whose return type already matches.
|
|
310
|
+
- For a trivial one-liner you can skip both the import and the annotation with a lambda, which the type checker types contextually:
|
|
311
|
+
|
|
312
|
+
```python
|
|
313
|
+
Service("some-types", lambda ctx: {"number": 10}) # ctx is fully typed
|
|
314
|
+
```
|
|
292
315
|
|
|
293
316
|
### Options
|
|
294
317
|
|
|
@@ -578,7 +601,7 @@ The package installs a `requence-task` CLI that generates Python type stubs from
|
|
|
578
601
|
requence-task generate-types
|
|
579
602
|
```
|
|
580
603
|
|
|
581
|
-
Type stubs are written to `typings/requence/task
|
|
604
|
+
Type stubs are written to `typings/requence/task/`, giving you type hints for task inputs and results. As with the service stubs, Pylance and pyright read a top-level `typings/` directory automatically (point your stub path at a custom `--outdir` otherwise).
|
|
582
605
|
|
|
583
606
|
### Options
|
|
584
607
|
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "requence"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.8.1.dev55"
|
|
8
8
|
description = "Requence Service"
|
|
9
9
|
readme = { file = "README.md", content-type = "text/markdown" }
|
|
10
10
|
authors = [{ name = "Torsten Blindert" }]
|
|
@@ -14,12 +14,23 @@ dependencies = [
|
|
|
14
14
|
"requests>=2.32.2",
|
|
15
15
|
"colorama>=0.4.6",
|
|
16
16
|
"sseclient-py>=1.8.0",
|
|
17
|
+
# The portable msgpack wire (requence/wire_codec.py). NOT optional: the SDK
|
|
18
|
+
# declares `wire:msgpack1` in its AMQP client properties, which is a promise
|
|
19
|
+
# that it can decode a dispatch under that content type.
|
|
20
|
+
"msgpack>=1.0.5",
|
|
17
21
|
]
|
|
18
22
|
|
|
19
23
|
[project.scripts]
|
|
20
24
|
requence-service = "requence.service.cli:main"
|
|
21
25
|
requence-task = "requence.task.cli:main"
|
|
22
26
|
|
|
27
|
+
[dependency-groups]
|
|
28
|
+
dev = ["pytest>=8"]
|
|
29
|
+
|
|
30
|
+
[tool.pytest.ini_options]
|
|
31
|
+
testpaths = ["tests"]
|
|
32
|
+
pythonpath = ["."]
|
|
33
|
+
|
|
23
34
|
[tool.setuptools]
|
|
24
35
|
include-package-data = true
|
|
25
36
|
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""Callback references (mirrors @requence/callbacks)."""
|
|
2
|
+
|
|
3
|
+
from .context import CallbackEgressContext, CallbackIngressContext, CallbackRegistration
|
|
4
|
+
from .handler import create_requence_callback_handler
|
|
5
|
+
|
|
6
|
+
__all__ = [
|
|
7
|
+
"CallbackEgressContext",
|
|
8
|
+
"CallbackIngressContext",
|
|
9
|
+
"CallbackRegistration",
|
|
10
|
+
"create_requence_callback_handler",
|
|
11
|
+
]
|
|
@@ -0,0 +1,25 @@
|
|
|
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 ⇒ functions fail loud.
|
|
17
|
+
on_callback: Callable[[Callable[[Any], None]], CallbackRegistration] | None
|
|
18
|
+
# The emission the value belongs to (embedded in callback references).
|
|
19
|
+
output_name: str | None
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class CallbackIngressContext(Protocol):
|
|
23
|
+
# Invocation dispatch for reconstructed callbacks; payload is the
|
|
24
|
+
# CallbackObject plus {"arg": ...}. Absent ⇒ invoking is a no-op.
|
|
25
|
+
on_callback_invoke: Callable[[dict], None] | None
|
|
@@ -0,0 +1,56 @@
|
|
|
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
|
+
Ingress reconstructs the reference into a callable that dispatches through
|
|
12
|
+
``ctx.on_callback_invoke`` — with no ``on_callback_invoke`` provided, invoking
|
|
13
|
+
the callback is a no-op; callers that forbid callbacks pass a raising
|
|
14
|
+
implementation.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from typing import Any
|
|
18
|
+
|
|
19
|
+
from ..transformer import TransformContext, TransformPath, ValueHandler
|
|
20
|
+
from ..wire import REFERENCE_TAG_KEY, is_callback_object
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _serialize(callback: Any, ctx: TransformContext, path: TransformPath) -> dict:
|
|
24
|
+
on_callback = getattr(ctx, "on_callback", None)
|
|
25
|
+
if on_callback is None:
|
|
26
|
+
# handler raises are not path-wrapped by the transformer — carry the
|
|
27
|
+
# position in the message ourselves
|
|
28
|
+
raise Exception(
|
|
29
|
+
"functions are not serializable on this boundary (no ctx.on_callback) "
|
|
30
|
+
f'at path "{".".join(map(str, path))}"'
|
|
31
|
+
)
|
|
32
|
+
return {
|
|
33
|
+
**on_callback(callback),
|
|
34
|
+
"outputName": getattr(ctx, "output_name", None),
|
|
35
|
+
"propertyPath": list(path),
|
|
36
|
+
REFERENCE_TAG_KEY: "RequenceCallback",
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _deserialize(ref: dict, ctx: TransformContext, _path: TransformPath):
|
|
41
|
+
def invoke(arg: Any) -> None:
|
|
42
|
+
on_callback_invoke = getattr(ctx, "on_callback_invoke", None)
|
|
43
|
+
if on_callback_invoke is not None:
|
|
44
|
+
on_callback_invoke({**ref, "arg": arg})
|
|
45
|
+
|
|
46
|
+
return invoke
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def create_requence_callback_handler() -> ValueHandler:
|
|
50
|
+
return ValueHandler(
|
|
51
|
+
tag="RequenceCallback",
|
|
52
|
+
can_handle=callable,
|
|
53
|
+
serialize=_serialize,
|
|
54
|
+
is_reference=is_callback_object,
|
|
55
|
+
deserialize=_deserialize,
|
|
56
|
+
)
|
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
"""AMQP connection client properties — the Python mirror of
|
|
2
|
+
``packages/helpers/src/protocol/clientProperties.ts``.
|
|
3
|
+
|
|
4
|
+
That TS file is the contract and carries the full rationale. This module exists
|
|
5
|
+
so the Python SDK announces itself with the IDENTICAL key set; the parity is
|
|
6
|
+
locked by ``tests/test_client_properties.py``, which reads the TS source and
|
|
7
|
+
asserts the keys match. Changing a key is a wire change: both SDKs ship it
|
|
8
|
+
together.
|
|
9
|
+
|
|
10
|
+
Write side only for the announcements — reading connections back is
|
|
11
|
+
``ui/backend``'s job. The capability section at the bottom is the other way
|
|
12
|
+
round: the operator declares what a dispatch requires, and this SDK only reads.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from typing import Any, Dict, Iterable, List, Optional
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"CLIENT_PROPERTY_KEYS",
|
|
19
|
+
"IDENTITY_HEADER_KEYS",
|
|
20
|
+
"CAPABILITY_HEADER_KEYS",
|
|
21
|
+
"MAX_SERVICE_NAME_LENGTH",
|
|
22
|
+
"MAX_CAPABILITIES_LENGTH",
|
|
23
|
+
"WIRE_JSON_1",
|
|
24
|
+
"WIRE_MSGPACK_1",
|
|
25
|
+
"SERVICE_WIRE_CAPABILITIES",
|
|
26
|
+
"build_service_client_properties",
|
|
27
|
+
"build_service_identity_headers",
|
|
28
|
+
"read_required_capabilities",
|
|
29
|
+
"unsupported_capabilities",
|
|
30
|
+
"unsupported_capability_message",
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
# The pinned, namespaced property set. Flat strings on purpose.
|
|
34
|
+
CLIENT_PROPERTY_KEYS = {
|
|
35
|
+
"libVersion": "requence_lib_version",
|
|
36
|
+
"serviceVersion": "requence_service_version",
|
|
37
|
+
"capabilities": "requence_capabilities",
|
|
38
|
+
# Author-chosen debugging label. Optional, non-unique, unvalidated —
|
|
39
|
+
# NOTHING may key off or branch on it.
|
|
40
|
+
"name": "requence_name",
|
|
41
|
+
# Marks a developer's local dev-overlay connection. Only the marker travels,
|
|
42
|
+
# never the devKey (which is an access-token value).
|
|
43
|
+
"devOverlay": "requence_dev_overlay",
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
# The name is author-controlled text and the whole client-properties table
|
|
47
|
+
# travels inside the connection frame, so an unbounded string is a
|
|
48
|
+
# connection-level failure. Capped here and truncated AGAIN on read.
|
|
49
|
+
MAX_SERVICE_NAME_LENGTH = 64
|
|
50
|
+
MAX_CAPABILITIES_LENGTH = 512
|
|
51
|
+
|
|
52
|
+
WIRE_JSON_1 = "wire:json1"
|
|
53
|
+
# The portable msgpack subset in ``requence/wire_codec.py``. Claimed only by an
|
|
54
|
+
# SDK that can DECODE it on the dispatch wire — a service echoes the codec it was
|
|
55
|
+
# addressed in, so claiming this is a promise about READING, and the reply
|
|
56
|
+
# direction needs no capability of its own.
|
|
57
|
+
WIRE_MSGPACK_1 = "wire:msgpack1"
|
|
58
|
+
SERVICE_WIRE_CAPABILITIES = [WIRE_JSON_1, WIRE_MSGPACK_1]
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _sanitize_label(value: str, max_length: int) -> str:
|
|
62
|
+
"""Drop control characters, trim, cap. Mirrors sanitizeLabel in the TS."""
|
|
63
|
+
return "".join(c for c in value if ord(c) >= 0x20 and ord(c) != 0x7F).strip()[
|
|
64
|
+
:max_length
|
|
65
|
+
]
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def build_service_client_properties(
|
|
69
|
+
*,
|
|
70
|
+
lib_version: str,
|
|
71
|
+
service_version: str,
|
|
72
|
+
name: Optional[str] = None,
|
|
73
|
+
dev_overlay: bool = False,
|
|
74
|
+
capabilities: Optional[Iterable[str]] = None,
|
|
75
|
+
) -> Dict[str, str]:
|
|
76
|
+
"""Build the properties handed to pika on connect (and therefore on every
|
|
77
|
+
reconnect, since the connection parameters are reused). Absent optional
|
|
78
|
+
fields are OMITTED, never sent blank."""
|
|
79
|
+
if capabilities is None:
|
|
80
|
+
capabilities = SERVICE_WIRE_CAPABILITIES
|
|
81
|
+
|
|
82
|
+
properties: Dict[str, str] = {
|
|
83
|
+
CLIENT_PROPERTY_KEYS["libVersion"]: lib_version,
|
|
84
|
+
CLIENT_PROPERTY_KEYS["serviceVersion"]: service_version,
|
|
85
|
+
CLIENT_PROPERTY_KEYS["capabilities"]: ",".join(capabilities)[
|
|
86
|
+
:MAX_CAPABILITIES_LENGTH
|
|
87
|
+
],
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
label = _sanitize_label(name, MAX_SERVICE_NAME_LENGTH) if name else ""
|
|
91
|
+
if label:
|
|
92
|
+
properties[CLIENT_PROPERTY_KEYS["name"]] = label
|
|
93
|
+
|
|
94
|
+
if dev_overlay:
|
|
95
|
+
properties[CLIENT_PROPERTY_KEYS["devOverlay"]] = "1"
|
|
96
|
+
|
|
97
|
+
return properties
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
# ─── The second announcement: per-run identity on the begin message ──────────
|
|
101
|
+
#
|
|
102
|
+
# The same three values as above, sent again on the ``begin`` publish, because
|
|
103
|
+
# they answer a DIFFERENT question: the client properties say "can this fleet
|
|
104
|
+
# decode msgpack?" (live, folded to the minimum, available before dispatch),
|
|
105
|
+
# these say "which build ran THIS node?" (exact, frozen into the NODE_START
|
|
106
|
+
# update). See the TS contract for the full rationale.
|
|
107
|
+
#
|
|
108
|
+
# Bare, un-namespaced names, matching the headers that already ride alongside
|
|
109
|
+
# them (``taskId``, ``index``, ``connectionId``, ``version``).
|
|
110
|
+
IDENTITY_HEADER_KEYS = {
|
|
111
|
+
"libVersion": "libVersion",
|
|
112
|
+
"name": "serviceName",
|
|
113
|
+
"capabilities": "capabilities",
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def build_service_identity_headers(
|
|
118
|
+
*,
|
|
119
|
+
lib_version: str,
|
|
120
|
+
name: Optional[str] = None,
|
|
121
|
+
capabilities: Optional[Iterable[str]] = None,
|
|
122
|
+
) -> Dict[str, str]:
|
|
123
|
+
"""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."""
|
|
125
|
+
if capabilities is None:
|
|
126
|
+
capabilities = SERVICE_WIRE_CAPABILITIES
|
|
127
|
+
|
|
128
|
+
headers: Dict[str, str] = {
|
|
129
|
+
IDENTITY_HEADER_KEYS["libVersion"]: lib_version,
|
|
130
|
+
IDENTITY_HEADER_KEYS["capabilities"]: ",".join(capabilities)[
|
|
131
|
+
:MAX_CAPABILITIES_LENGTH
|
|
132
|
+
],
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
label = _sanitize_label(name, MAX_SERVICE_NAME_LENGTH) if name else ""
|
|
136
|
+
if label:
|
|
137
|
+
headers[IDENTITY_HEADER_KEYS["name"]] = label
|
|
138
|
+
|
|
139
|
+
return headers
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
# ─── The dispatch direction: what a message REQUIRES of its consumer ─────────
|
|
143
|
+
#
|
|
144
|
+
# The mirror of the TS contract's `requires` section. READ SIDE ONLY here: the
|
|
145
|
+
# tokens are declared by the operator, which is TypeScript, so Python never
|
|
146
|
+
# builds this header — it only ever answers "can this build satisfy it?".
|
|
147
|
+
#
|
|
148
|
+
# It is a HEADER, never a body field: the body is precisely the thing this build
|
|
149
|
+
# may be unable to decode, so a requirement stated inside it is unreadable
|
|
150
|
+
# exactly when it matters.
|
|
151
|
+
CAPABILITY_HEADER_KEYS = {
|
|
152
|
+
# dispatch → service: the tokens this message needs. Absent when it needs
|
|
153
|
+
# nothing beyond the floor every SDK speaks.
|
|
154
|
+
"requires": "requires",
|
|
155
|
+
# service → operator: this replica cannot satisfy `requires`. Sent by
|
|
156
|
+
# REPUBLISHING to `<exchange>-retry`, never by nacking — a nack cannot modify
|
|
157
|
+
# the message, these are classic queues (so there is no `x-delivery-count`
|
|
158
|
+
# either), and with no counter anywhere the message would requeue forever.
|
|
159
|
+
"mismatch": "capabilityMismatch",
|
|
160
|
+
# operator → service, on a reroute: how many reroutes are left. Named for
|
|
161
|
+
# reroutes and NOT for retries on purpose — it is its own allowance, never
|
|
162
|
+
# the node's `retry` budget. The operator owns the count; this SDK only ever
|
|
163
|
+
# echoes it back.
|
|
164
|
+
"reroutes": "capabilityReroutes",
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def _parse_capability_list(raw: Optional[str]) -> List[str]:
|
|
169
|
+
"""Caps the whole string BEFORE splitting, so an unbounded writer cannot push
|
|
170
|
+
an unbounded list through. A token cut in half by that cap simply matches no
|
|
171
|
+
known capability, which can only ever UNDER-claim — the safe direction."""
|
|
172
|
+
if not raw:
|
|
173
|
+
return []
|
|
174
|
+
|
|
175
|
+
tokens: List[str] = []
|
|
176
|
+
for token in raw[:MAX_CAPABILITIES_LENGTH].split(","):
|
|
177
|
+
stripped = token.strip()
|
|
178
|
+
if stripped and stripped not in tokens:
|
|
179
|
+
tokens.append(stripped)
|
|
180
|
+
return tokens
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def read_required_capabilities(headers: Any) -> List[str]:
|
|
184
|
+
"""The tokens a dispatch declared in its `requires` header. Never raises and
|
|
185
|
+
never trusts the writer: an absent, blank or non-string header means
|
|
186
|
+
"requires nothing", which is how every message published before this existed
|
|
187
|
+
reads."""
|
|
188
|
+
if not isinstance(headers, dict):
|
|
189
|
+
return []
|
|
190
|
+
|
|
191
|
+
raw = headers.get(CAPABILITY_HEADER_KEYS["requires"])
|
|
192
|
+
return _parse_capability_list(raw if isinstance(raw, str) else None)
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
def unsupported_capabilities(
|
|
196
|
+
required: Iterable[str],
|
|
197
|
+
supported: Optional[Iterable[str]] = None,
|
|
198
|
+
) -> List[str]:
|
|
199
|
+
"""The tokens this build cannot satisfy. Anything unrecognised counts as
|
|
200
|
+
unsupported — an unknown token is a capability from a newer operator, and
|
|
201
|
+
guessing it is harmless would defeat the point of declaring it."""
|
|
202
|
+
known = set(SERVICE_WIRE_CAPABILITIES if supported is None else supported)
|
|
203
|
+
return [token for token in required if token not in known]
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def unsupported_capability_message(unsupported: Iterable[str]) -> str:
|
|
207
|
+
"""The one diagnostic string, identical in both SDKs, so the operator can
|
|
208
|
+
surface it verbatim. Named and deliberate: the point of the mechanism is that
|
|
209
|
+
the failure is this message and never whatever incidental exception the
|
|
210
|
+
undecodable payload would have produced."""
|
|
211
|
+
return "unsupported wire capability: " + ", ".join(unsupported)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
from typing import Any, Optional, Callable, cast
|
|
2
2
|
from .exceptions import RetryException, AbortException, SkipException
|
|
3
|
-
from .utils import OutputValue
|
|
3
|
+
from .utils import OutputValue
|
|
4
4
|
import threading
|
|
5
5
|
import datetime
|
|
6
6
|
|
|
@@ -11,52 +11,47 @@ def parse_iso_format(iso: str):
|
|
|
11
11
|
class Debug:
|
|
12
12
|
def __init__(self, on_log: Callable[[str, Any], None]):
|
|
13
13
|
self.__on_log = on_log
|
|
14
|
-
|
|
14
|
+
|
|
15
15
|
def log(self, *data: Any):
|
|
16
16
|
self.__on_log("log", data)
|
|
17
|
-
|
|
17
|
+
|
|
18
18
|
def info(self, *data: Any):
|
|
19
19
|
self.__on_log("info", data)
|
|
20
|
-
|
|
20
|
+
|
|
21
21
|
def warn(self, *data: Any):
|
|
22
22
|
self.__on_log("warn", data)
|
|
23
|
-
|
|
23
|
+
|
|
24
24
|
def error(self, *data: Any):
|
|
25
25
|
self.__on_log("error", data)
|
|
26
26
|
|
|
27
27
|
class Context[I, C]:
|
|
28
|
+
"""Handler-facing context. `input` and `configuration` arrive already
|
|
29
|
+
rehydrated — reference reconstruction happens at the service's single
|
|
30
|
+
inbound boundary (requence/service/boundary.py), not here."""
|
|
31
|
+
|
|
28
32
|
def __init__(
|
|
29
|
-
self,
|
|
33
|
+
self,
|
|
30
34
|
task_id: str,
|
|
31
35
|
input: Any,
|
|
32
36
|
configuration: Any,
|
|
33
37
|
on_log: Callable[[str, Any], None],
|
|
34
38
|
on_defer: Callable[[Optional[str]], str],
|
|
35
|
-
on_callback: Callable[[str, str, Optional[str], list[str | int], Any], None],
|
|
36
39
|
terminated: threading.Event
|
|
37
40
|
):
|
|
38
41
|
|
|
39
42
|
self.task_id = task_id
|
|
40
43
|
self.terminated = terminated
|
|
41
|
-
self.input = cast(I,
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
def error(_0: str, _1: str, _2: Optional[str], _3: list[str | int], _4: Any):
|
|
45
|
-
raise Exception("configuration may not have callbacks")
|
|
46
|
-
|
|
47
|
-
self.configuration = cast(C, resolve_requence_types(
|
|
48
|
-
configuration,
|
|
49
|
-
error
|
|
50
|
-
))
|
|
44
|
+
self.input = cast(I, input)
|
|
45
|
+
self.configuration = cast(C, configuration)
|
|
51
46
|
self.__on_defer = on_defer
|
|
52
47
|
self.debug = Debug(on_log)
|
|
53
|
-
|
|
48
|
+
|
|
54
49
|
def retry(self, delay: Optional[int] = None):
|
|
55
50
|
raise RetryException(delay)
|
|
56
51
|
|
|
57
52
|
def abort(self, reason: Optional[str] = ''):
|
|
58
53
|
raise AbortException(reason)
|
|
59
|
-
|
|
54
|
+
|
|
60
55
|
def skip(self):
|
|
61
56
|
raise SkipException()
|
|
62
57
|
|
|
@@ -64,6 +59,4 @@ class Context[I, C]:
|
|
|
64
59
|
return OutputValue(output_name=output_name, value=value)
|
|
65
60
|
|
|
66
61
|
def defer(self, reason: Optional[str] = None):
|
|
67
|
-
self.__on_defer(reason)
|
|
68
|
-
|
|
69
|
-
|
|
62
|
+
return self.__on_defer(reason)
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
from typing import Optional
|
|
2
|
+
|
|
3
|
+
from .client_properties import unsupported_capability_message
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class TaskException(Exception):
|
|
7
|
+
def __init__(self, message:str, task_template: str):
|
|
8
|
+
super().__init__(message)
|
|
9
|
+
self.task_template = task_template
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class RequenceUnreachableException(Exception):
|
|
13
|
+
"""Raised when the requence system could not be reached — e.g. during a
|
|
14
|
+
maintenance window or deploy, when the ui backend is unreachable
|
|
15
|
+
(connection refused / timeout / DNS failure) or an ingress returns a
|
|
16
|
+
gateway error (502/503/504). Callers should treat this as transient and
|
|
17
|
+
retry later.
|
|
18
|
+
"""
|
|
19
|
+
def __init__(self, status: Optional[int] = None):
|
|
20
|
+
super().__init__("The requence system is currently not reachable. Please retry later.")
|
|
21
|
+
self.status = status
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class UnsupportedCapabilityException(Exception):
|
|
25
|
+
"""Raised when a dispatch declares a capability (``requires`` header) this
|
|
26
|
+
build cannot satisfy, so it is refused before its body is ever decoded.
|
|
27
|
+
|
|
28
|
+
A NAMED exception on purpose: the point of the header is that a mismatch
|
|
29
|
+
reports the missing capability, instead of whatever incidental exception the
|
|
30
|
+
undecodable payload would otherwise have produced — a bare ``ValueError``
|
|
31
|
+
from the JSON decoder says nothing about why this box was the wrong one. The
|
|
32
|
+
message travels to the operator, which surfaces it on the node.
|
|
33
|
+
"""
|
|
34
|
+
def __init__(self, unsupported: list[str]):
|
|
35
|
+
super().__init__(unsupported_capability_message(unsupported))
|
|
36
|
+
self.capabilities = list(unsupported)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class RetryException(Exception):
|
|
40
|
+
def __init__(self, delay: Optional[int]):
|
|
41
|
+
self.delay = delay
|
|
42
|
+
|
|
43
|
+
class AbortException(Exception):
|
|
44
|
+
pass
|
|
45
|
+
|
|
46
|
+
class SkipException(Exception):
|
|
47
|
+
pass
|
|
48
|
+
|
|
49
|
+
class StopException(Exception):
|
|
50
|
+
pass
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""Byte references — files and streams (mirrors the @requence/files client surface)."""
|
|
2
|
+
|
|
3
|
+
from .errors import RequenceStreamTruncatedError
|
|
4
|
+
from .pending_uploads import BackgroundUpload
|
|
5
|
+
from .requence_file import RequenceFile, RequenceFileOptions
|
|
6
|
+
from .requence_stream import RequenceStream, RequenceStreamOptions
|
|
7
|
+
from .sanitize_log_data import sanitize_log_data
|
|
8
|
+
from .transport import (
|
|
9
|
+
DEFAULT_HTTP_CLIENT,
|
|
10
|
+
GeneratorReader,
|
|
11
|
+
HttpClient,
|
|
12
|
+
HttpResponse,
|
|
13
|
+
UrllibHttpClient,
|
|
14
|
+
assert_ok,
|
|
15
|
+
)
|
|
16
|
+
from .handlers import (
|
|
17
|
+
create_claim_check_handler,
|
|
18
|
+
create_requence_file_handler,
|
|
19
|
+
create_requence_stream_handler,
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
__all__ = [
|
|
23
|
+
"BackgroundUpload",
|
|
24
|
+
"RequenceStreamTruncatedError",
|
|
25
|
+
"RequenceFile",
|
|
26
|
+
"RequenceFileOptions",
|
|
27
|
+
"RequenceStream",
|
|
28
|
+
"RequenceStreamOptions",
|
|
29
|
+
"sanitize_log_data",
|
|
30
|
+
"DEFAULT_HTTP_CLIENT",
|
|
31
|
+
"GeneratorReader",
|
|
32
|
+
"HttpClient",
|
|
33
|
+
"HttpResponse",
|
|
34
|
+
"UrllibHttpClient",
|
|
35
|
+
"assert_ok",
|
|
36
|
+
"create_claim_check_handler",
|
|
37
|
+
"create_requence_file_handler",
|
|
38
|
+
"create_requence_stream_handler",
|
|
39
|
+
]
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""Typed stream errors (mirrors packages/files/src/errors.ts)."""
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
class RequenceStreamTruncatedError(Exception):
|
|
5
|
+
"""The producer aborted / vanished mid-stream, or the transport dropped
|
|
6
|
+
before the terminal frame: the bytes read so far are NOT the whole stream.
|
|
7
|
+
Surfaced instead of a clean-looking EOF."""
|
|
8
|
+
|
|
9
|
+
def __init__(self, reason: str | None = None):
|
|
10
|
+
super().__init__(f"stream truncated{f': {reason}' if reason else ''}")
|
|
11
|
+
self.reason = reason
|