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.
Files changed (77) hide show
  1. {requence-0.7.1 → requence-0.8.1.dev55}/PKG-INFO +39 -3
  2. requence-0.7.1/requence.egg-info/PKG-INFO → requence-0.8.1.dev55/README.md +37 -14
  3. {requence-0.7.1 → requence-0.8.1.dev55}/pyproject.toml +12 -1
  4. requence-0.8.1.dev55/requence/callbacks/__init__.py +11 -0
  5. requence-0.8.1.dev55/requence/callbacks/context.py +25 -0
  6. requence-0.8.1.dev55/requence/callbacks/handler.py +56 -0
  7. requence-0.8.1.dev55/requence/client_properties.py +211 -0
  8. {requence-0.7.1 → requence-0.8.1.dev55}/requence/context.py +15 -22
  9. requence-0.8.1.dev55/requence/exceptions.py +50 -0
  10. requence-0.8.1.dev55/requence/files/__init__.py +39 -0
  11. requence-0.8.1.dev55/requence/files/errors.py +11 -0
  12. requence-0.8.1.dev55/requence/files/handlers/__init__.py +9 -0
  13. requence-0.8.1.dev55/requence/files/handlers/claim_check_handler.py +177 -0
  14. requence-0.8.1.dev55/requence/files/handlers/context.py +73 -0
  15. requence-0.8.1.dev55/requence/files/handlers/file_handler.py +94 -0
  16. requence-0.8.1.dev55/requence/files/handlers/stream_handler.py +134 -0
  17. requence-0.8.1.dev55/requence/files/pending_uploads.py +41 -0
  18. requence-0.8.1.dev55/requence/files/requence_file.py +98 -0
  19. requence-0.8.1.dev55/requence/files/requence_stream.py +89 -0
  20. requence-0.8.1.dev55/requence/files/sanitize_log_data.py +32 -0
  21. requence-0.8.1.dev55/requence/files/stream_framing.py +81 -0
  22. requence-0.8.1.dev55/requence/files/transport.py +172 -0
  23. requence-0.8.1.dev55/requence/internal_types.py +33 -0
  24. requence-0.8.1.dev55/requence/reachable.py +40 -0
  25. requence-0.8.1.dev55/requence/requence_file.py +7 -0
  26. requence-0.8.1.dev55/requence/requence_stream.py +7 -0
  27. requence-0.8.1.dev55/requence/service/__init__.py +927 -0
  28. requence-0.8.1.dev55/requence/service/boundary.py +240 -0
  29. {requence-0.7.1 → requence-0.8.1.dev55}/requence/service/cli.py +10 -4
  30. requence-0.8.1.dev55/requence/service/transformer.py +21 -0
  31. {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/__init__.py +2 -0
  32. {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/abort_task.py +2 -3
  33. {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/ack_task.py +4 -4
  34. {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/cli.py +11 -5
  35. {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/get_task.py +7 -8
  36. requence-0.8.1.dev55/requence/task/ingress.py +94 -0
  37. {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/protect_task.py +2 -3
  38. {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/task.py +80 -46
  39. {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/task_watcher.py +15 -11
  40. requence-0.8.1.dev55/requence/task/utils.py +38 -0
  41. requence-0.8.1.dev55/requence/transformer/__init__.py +35 -0
  42. requence-0.8.1.dev55/requence/transformer/context.py +43 -0
  43. requence-0.8.1.dev55/requence/transformer/errors.py +31 -0
  44. requence-0.8.1.dev55/requence/transformer/guards.py +34 -0
  45. requence-0.8.1.dev55/requence/transformer/message_handler.py +41 -0
  46. requence-0.8.1.dev55/requence/transformer/transform.py +169 -0
  47. requence-0.8.1.dev55/requence/transformer/value_handler.py +39 -0
  48. requence-0.8.1.dev55/requence/transformer/walk.py +60 -0
  49. requence-0.8.1.dev55/requence/utils.py +24 -0
  50. requence-0.8.1.dev55/requence/wire.py +128 -0
  51. requence-0.8.1.dev55/requence/wire_codec.py +169 -0
  52. requence-0.7.1/README.md → requence-0.8.1.dev55/requence.egg-info/PKG-INFO +50 -2
  53. requence-0.8.1.dev55/requence.egg-info/SOURCES.txt +67 -0
  54. {requence-0.7.1 → requence-0.8.1.dev55}/requence.egg-info/requires.txt +1 -0
  55. requence-0.8.1.dev55/tests/test_client_properties.py +276 -0
  56. requence-0.8.1.dev55/tests/test_wire.py +109 -0
  57. requence-0.8.1.dev55/tests/test_wire_codec.py +233 -0
  58. requence-0.7.1/requence/exceptions.py +0 -20
  59. requence-0.7.1/requence/internal_types.py +0 -27
  60. requence-0.7.1/requence/requence_file.py +0 -61
  61. requence-0.7.1/requence/requence_stream.py +0 -52
  62. requence-0.7.1/requence/service/__init__.py +0 -510
  63. requence-0.7.1/requence/task/utils.py +0 -58
  64. requence-0.7.1/requence/utils.py +0 -194
  65. requence-0.7.1/requence.egg-info/SOURCES.txt +0 -33
  66. {requence-0.7.1 → requence-0.8.1.dev55}/MANIFEST.in +0 -0
  67. {requence-0.7.1 → requence-0.8.1.dev55}/requence/__init__.py +0 -0
  68. {requence-0.7.1 → requence-0.8.1.dev55}/requence/obfuscase.py +0 -0
  69. {requence-0.7.1 → requence-0.8.1.dev55}/requence/py.typed +0 -0
  70. {requence-0.7.1 → requence-0.8.1.dev55}/requence/requence_callback.py +0 -0
  71. {requence-0.7.1 → requence-0.8.1.dev55}/requence/service/types.py +0 -0
  72. {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/types.py +0 -0
  73. {requence-0.7.1 → requence-0.8.1.dev55}/requence/task/updates.py +0 -0
  74. {requence-0.7.1 → requence-0.8.1.dev55}/requence.egg-info/dependency_links.txt +0 -0
  75. {requence-0.7.1 → requence-0.8.1.dev55}/requence.egg-info/entry_points.txt +0 -0
  76. {requence-0.7.1 → requence-0.8.1.dev55}/requence.egg-info/top_level.txt +0 -0
  77. {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.7.1
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/`. Point your type checker at this directory to get type hints for `ctx.input`, `ctx.configuration`, and `ctx.to_output()`.
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/`. Point your type checker at this directory to get type hints for task inputs and results.
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/`. Point your type checker at this directory to get type hints for `ctx.input`, `ctx.configuration`, and `ctx.to_output()`.
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/`. Point your type checker at this directory to get type hints for task inputs and results.
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.1"
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, resolve_requence_types
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, resolve_requence_types(input, on_callback))
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