cruma-tron-runner 0.1.0__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.
- cruma_tron_runner-0.1.0/.gitignore +15 -0
- cruma_tron_runner-0.1.0/LICENSE +21 -0
- cruma_tron_runner-0.1.0/PKG-INFO +102 -0
- cruma_tron_runner-0.1.0/README.md +76 -0
- cruma_tron_runner-0.1.0/pyproject.toml +49 -0
- cruma_tron_runner-0.1.0/src/tron_runner/__init__.py +66 -0
- cruma_tron_runner-0.1.0/src/tron_runner/_frames.py +119 -0
- cruma_tron_runner-0.1.0/src/tron_runner/_version.py +1 -0
- cruma_tron_runner-0.1.0/src/tron_runner/errors.py +138 -0
- cruma_tron_runner-0.1.0/src/tron_runner/generated/__init__.py +0 -0
- cruma_tron_runner-0.1.0/src/tron_runner/generated/protocol.py +1670 -0
- cruma_tron_runner-0.1.0/src/tron_runner/generated/protocol_version.py +6 -0
- cruma_tron_runner-0.1.0/src/tron_runner/outcomes.py +46 -0
- cruma_tron_runner-0.1.0/src/tron_runner/py.typed +0 -0
- cruma_tron_runner-0.1.0/src/tron_runner/runner.py +474 -0
- cruma_tron_runner-0.1.0/src/tron_runner/secret_store.py +76 -0
- cruma_tron_runner-0.1.0/tests/__init__.py +0 -0
- cruma_tron_runner-0.1.0/tests/fake_tron.py +120 -0
- cruma_tron_runner-0.1.0/tests/test_runner.py +483 -0
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/node_modules
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.pyc
|
|
4
|
+
/conformance/.run
|
|
5
|
+
/.binding-checks
|
|
6
|
+
/packages/go/.bin
|
|
7
|
+
/packages/typescript/dist
|
|
8
|
+
/packages/python/.venv
|
|
9
|
+
/packages/python/dist
|
|
10
|
+
*.egg-info
|
|
11
|
+
/packages/dotnet/**/bin/
|
|
12
|
+
/packages/dotnet/**/obj/
|
|
13
|
+
/packages/dotnet/adapter/out/
|
|
14
|
+
/packages/dotnet/pack/
|
|
15
|
+
/packages/rust/target
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Umbra-Yurei
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: cruma-tron-runner
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Run Tron jobs on your own machines: an async runner SDK for Tron's runner protocol
|
|
5
|
+
Project-URL: Homepage, https://github.com/umbra-yurei/tron-runner-sdk
|
|
6
|
+
Project-URL: Repository, https://github.com/umbra-yurei/tron-runner-sdk
|
|
7
|
+
Author: Umbra-Yurei
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: jobs,runner,scheduler,tron,websocket
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Framework :: AsyncIO
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Python: >=3.11
|
|
20
|
+
Requires-Dist: websockets>=14
|
|
21
|
+
Provides-Extra: dev
|
|
22
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
23
|
+
Requires-Dist: mypy>=1.13; extra == 'dev'
|
|
24
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# cruma-tron-runner
|
|
28
|
+
|
|
29
|
+
Run [Tron](https://github.com/umbra-yurei/tron) jobs on your own machines. Tron pushes work to a connected runner;
|
|
30
|
+
the runner accepts it immediately, runs your async handler, and reports `Ok(...)` or `Err(...)`.
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
pip install cruma-tron-runner
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Python 3.11 or newer. The only dependency is [`websockets`](https://websockets.readthedocs.io).
|
|
37
|
+
|
|
38
|
+
<!-- tron-runner-example:start -->
|
|
39
|
+
```python
|
|
40
|
+
import os
|
|
41
|
+
|
|
42
|
+
from tron_runner import Delivery, FileSecretStore, Ok, Outcome, Runner
|
|
43
|
+
|
|
44
|
+
runner = Runner(
|
|
45
|
+
os.environ["TRON_URL"],
|
|
46
|
+
os.environ["TRON_WORKER_KEY"],
|
|
47
|
+
secret_store=FileSecretStore(os.environ["TRON_SECRET_DIR"]),
|
|
48
|
+
)
|
|
49
|
+
|
|
50
|
+
async def send_report(delivery: Delivery) -> Outcome:
|
|
51
|
+
# Ok marks the run succeeded and Err marks it failed; both carry a message.
|
|
52
|
+
return Ok(f"sent the report for {delivery.job_name}")
|
|
53
|
+
|
|
54
|
+
runner.register("send-report", send_report)
|
|
55
|
+
async with runner:
|
|
56
|
+
... # keep the process alive; leaving this block finishes in-flight work, reports it, then closes
|
|
57
|
+
```
|
|
58
|
+
<!-- tron-runner-example:end -->
|
|
59
|
+
|
|
60
|
+
## What the SDK does
|
|
61
|
+
|
|
62
|
+
- **Connects and authenticates** with the worker API key. A bad key raises `AuthenticationFailedError`; a first
|
|
63
|
+
attempt that cannot reach Tron raises `UnreachableError` (both are `ConnectError`s carrying the generated
|
|
64
|
+
`ConnectFailure` reason, and neither is retried). Once connected, a lost connection is re-established
|
|
65
|
+
automatically with exponential backoff (100 ms, doubling, capped at 5 s) and a fresh authenticate and announce.
|
|
66
|
+
- **Announces** the registered handler keys, `concurrency_capacity`, optional `display_name` and `runner_version`,
|
|
67
|
+
the SDK version and the protocol version. A refused announcement raises `AnnouncementRejectedError`.
|
|
68
|
+
- **Accepts automatically** when work arrives, then persists the one-time delivery secret *before* running the
|
|
69
|
+
handler. A refused accept (`AcceptRefusedError`, with the generated `AcceptRefusal` reason) means the handler was not run.
|
|
70
|
+
- **Reports once** with the stored secret. Returning `Ok(message)` or `Err(message)` is the report; an exception
|
|
71
|
+
from the handler is reported as `Err`. The report may go out on a later connection than the one that accepted.
|
|
72
|
+
A rejected report raises `ReportRejectedError` (generated `ReportRejection` reason) and keeps the stored secret.
|
|
73
|
+
- **Shuts down gracefully:** `await runner.stop()` takes no new work, waits for in-flight handlers and Tron's answer
|
|
74
|
+
to their reports, then disconnects.
|
|
75
|
+
|
|
76
|
+
Errors Tron raises while the runner works in the background are passed to the `on_error` callback (or logged).
|
|
77
|
+
`on_connected`, `on_delivery_accepted` and `on_report_recorded` observe the lifecycle.
|
|
78
|
+
|
|
79
|
+
### Secrets and restarts
|
|
80
|
+
|
|
81
|
+
The delivery secret is shown once and `report` must echo it, so it is the only state that survives a restart.
|
|
82
|
+
`FileSecretStore` keeps one `0600` file per delivery in a directory you choose. Implement the `SecretStore`
|
|
83
|
+
protocol (`save`, `load`, `remove`, `pending`) to keep secrets in a database or secret manager instead.
|
|
84
|
+
After a restart, `await runner.pending()` lists deliveries accepted but not yet reported and
|
|
85
|
+
`await runner.report_pending(delivery_id, Ok("..."))` reports one.
|
|
86
|
+
|
|
87
|
+
### Several handlers per runner
|
|
88
|
+
|
|
89
|
+
A runner can register any number of handlers. Each `work` frame names the handler key it was dispatched for, and
|
|
90
|
+
the runner runs the handler registered under that key. A delivery for a key with no registered handler is not
|
|
91
|
+
accepted and is passed to `on_error` as `UnknownHandlerError` (with `delivery_id` and `handler_key`).
|
|
92
|
+
Multi-handler routing needs a Tron whose `work` frame carries `handler_key`.
|
|
93
|
+
|
|
94
|
+
## Protocol messages are generated
|
|
95
|
+
|
|
96
|
+
`tron_runner.generated.protocol` is emitted from Tron's published AsyncAPI document by the repository's
|
|
97
|
+
`npm run generate`; nothing in this package hand-writes a frame. `tron_runner.PROTOCOL_VERSION` is the protocol
|
|
98
|
+
version this release speaks. CI fails if the generated files are stale (`npm run check:generated`) or if the SDK
|
|
99
|
+
does not decode every frame the document defines (importing `tron_runner` checks that against the generated
|
|
100
|
+
`ServerFrameKind`).
|
|
101
|
+
|
|
102
|
+
MIT licensed.
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# cruma-tron-runner
|
|
2
|
+
|
|
3
|
+
Run [Tron](https://github.com/umbra-yurei/tron) jobs on your own machines. Tron pushes work to a connected runner;
|
|
4
|
+
the runner accepts it immediately, runs your async handler, and reports `Ok(...)` or `Err(...)`.
|
|
5
|
+
|
|
6
|
+
```sh
|
|
7
|
+
pip install cruma-tron-runner
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Python 3.11 or newer. The only dependency is [`websockets`](https://websockets.readthedocs.io).
|
|
11
|
+
|
|
12
|
+
<!-- tron-runner-example:start -->
|
|
13
|
+
```python
|
|
14
|
+
import os
|
|
15
|
+
|
|
16
|
+
from tron_runner import Delivery, FileSecretStore, Ok, Outcome, Runner
|
|
17
|
+
|
|
18
|
+
runner = Runner(
|
|
19
|
+
os.environ["TRON_URL"],
|
|
20
|
+
os.environ["TRON_WORKER_KEY"],
|
|
21
|
+
secret_store=FileSecretStore(os.environ["TRON_SECRET_DIR"]),
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
async def send_report(delivery: Delivery) -> Outcome:
|
|
25
|
+
# Ok marks the run succeeded and Err marks it failed; both carry a message.
|
|
26
|
+
return Ok(f"sent the report for {delivery.job_name}")
|
|
27
|
+
|
|
28
|
+
runner.register("send-report", send_report)
|
|
29
|
+
async with runner:
|
|
30
|
+
... # keep the process alive; leaving this block finishes in-flight work, reports it, then closes
|
|
31
|
+
```
|
|
32
|
+
<!-- tron-runner-example:end -->
|
|
33
|
+
|
|
34
|
+
## What the SDK does
|
|
35
|
+
|
|
36
|
+
- **Connects and authenticates** with the worker API key. A bad key raises `AuthenticationFailedError`; a first
|
|
37
|
+
attempt that cannot reach Tron raises `UnreachableError` (both are `ConnectError`s carrying the generated
|
|
38
|
+
`ConnectFailure` reason, and neither is retried). Once connected, a lost connection is re-established
|
|
39
|
+
automatically with exponential backoff (100 ms, doubling, capped at 5 s) and a fresh authenticate and announce.
|
|
40
|
+
- **Announces** the registered handler keys, `concurrency_capacity`, optional `display_name` and `runner_version`,
|
|
41
|
+
the SDK version and the protocol version. A refused announcement raises `AnnouncementRejectedError`.
|
|
42
|
+
- **Accepts automatically** when work arrives, then persists the one-time delivery secret *before* running the
|
|
43
|
+
handler. A refused accept (`AcceptRefusedError`, with the generated `AcceptRefusal` reason) means the handler was not run.
|
|
44
|
+
- **Reports once** with the stored secret. Returning `Ok(message)` or `Err(message)` is the report; an exception
|
|
45
|
+
from the handler is reported as `Err`. The report may go out on a later connection than the one that accepted.
|
|
46
|
+
A rejected report raises `ReportRejectedError` (generated `ReportRejection` reason) and keeps the stored secret.
|
|
47
|
+
- **Shuts down gracefully:** `await runner.stop()` takes no new work, waits for in-flight handlers and Tron's answer
|
|
48
|
+
to their reports, then disconnects.
|
|
49
|
+
|
|
50
|
+
Errors Tron raises while the runner works in the background are passed to the `on_error` callback (or logged).
|
|
51
|
+
`on_connected`, `on_delivery_accepted` and `on_report_recorded` observe the lifecycle.
|
|
52
|
+
|
|
53
|
+
### Secrets and restarts
|
|
54
|
+
|
|
55
|
+
The delivery secret is shown once and `report` must echo it, so it is the only state that survives a restart.
|
|
56
|
+
`FileSecretStore` keeps one `0600` file per delivery in a directory you choose. Implement the `SecretStore`
|
|
57
|
+
protocol (`save`, `load`, `remove`, `pending`) to keep secrets in a database or secret manager instead.
|
|
58
|
+
After a restart, `await runner.pending()` lists deliveries accepted but not yet reported and
|
|
59
|
+
`await runner.report_pending(delivery_id, Ok("..."))` reports one.
|
|
60
|
+
|
|
61
|
+
### Several handlers per runner
|
|
62
|
+
|
|
63
|
+
A runner can register any number of handlers. Each `work` frame names the handler key it was dispatched for, and
|
|
64
|
+
the runner runs the handler registered under that key. A delivery for a key with no registered handler is not
|
|
65
|
+
accepted and is passed to `on_error` as `UnknownHandlerError` (with `delivery_id` and `handler_key`).
|
|
66
|
+
Multi-handler routing needs a Tron whose `work` frame carries `handler_key`.
|
|
67
|
+
|
|
68
|
+
## Protocol messages are generated
|
|
69
|
+
|
|
70
|
+
`tron_runner.generated.protocol` is emitted from Tron's published AsyncAPI document by the repository's
|
|
71
|
+
`npm run generate`; nothing in this package hand-writes a frame. `tron_runner.PROTOCOL_VERSION` is the protocol
|
|
72
|
+
version this release speaks. CI fails if the generated files are stale (`npm run check:generated`) or if the SDK
|
|
73
|
+
does not decode every frame the document defines (importing `tron_runner` checks that against the generated
|
|
74
|
+
`ServerFrameKind`).
|
|
75
|
+
|
|
76
|
+
MIT licensed.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "cruma-tron-runner"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Run Tron jobs on your own machines: an async runner SDK for Tron's runner protocol"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.11"
|
|
13
|
+
authors = [{ name = "Umbra-Yurei" }]
|
|
14
|
+
keywords = ["tron", "scheduler", "runner", "jobs", "websocket"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Framework :: AsyncIO",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
"Typing :: Typed",
|
|
24
|
+
]
|
|
25
|
+
dependencies = ["websockets>=14"]
|
|
26
|
+
|
|
27
|
+
[project.optional-dependencies]
|
|
28
|
+
dev = ["pytest>=8", "mypy>=1.13", "build>=1.2"]
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Homepage = "https://github.com/umbra-yurei/tron-runner-sdk"
|
|
32
|
+
Repository = "https://github.com/umbra-yurei/tron-runner-sdk"
|
|
33
|
+
|
|
34
|
+
[tool.hatch.version]
|
|
35
|
+
path = "src/tron_runner/_version.py"
|
|
36
|
+
|
|
37
|
+
[tool.hatch.build.targets.wheel]
|
|
38
|
+
packages = ["src/tron_runner"]
|
|
39
|
+
|
|
40
|
+
[tool.pytest.ini_options]
|
|
41
|
+
testpaths = ["tests"]
|
|
42
|
+
|
|
43
|
+
[tool.mypy]
|
|
44
|
+
strict = true
|
|
45
|
+
files = ["src", "tests", "../../conformance/adapters/python"]
|
|
46
|
+
|
|
47
|
+
[[tool.mypy.overrides]]
|
|
48
|
+
module = "tron_runner.generated.*"
|
|
49
|
+
ignore_errors = true
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
"""Python SDK for running Tron jobs on your own machines.
|
|
2
|
+
|
|
3
|
+
runner = Runner("https://tron.example.com", token, secret_store=FileSecretStore("secrets"))
|
|
4
|
+
|
|
5
|
+
@runner.handler("send-report")
|
|
6
|
+
async def send_report(delivery: Delivery) -> Outcome:
|
|
7
|
+
return Ok("sent")
|
|
8
|
+
|
|
9
|
+
await runner.run()
|
|
10
|
+
|
|
11
|
+
Protocol messages are generated from Tron's published AsyncAPI document (`tron_runner.generated`);
|
|
12
|
+
`PROTOCOL_VERSION` is the runner protocol version this package speaks.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from ._version import __version__
|
|
16
|
+
from .errors import (
|
|
17
|
+
AcceptRefusedError,
|
|
18
|
+
AnnouncementRejectedError,
|
|
19
|
+
AuthenticationFailedError,
|
|
20
|
+
ConnectError,
|
|
21
|
+
DeliveryLostError,
|
|
22
|
+
MalformedFrameError,
|
|
23
|
+
MissingSecretError,
|
|
24
|
+
ProtocolViolationError,
|
|
25
|
+
ReportRejectedError,
|
|
26
|
+
RunnerCrashedError,
|
|
27
|
+
SecretStoreError,
|
|
28
|
+
TronRunnerError,
|
|
29
|
+
UnreachableError,
|
|
30
|
+
UnknownHandlerError,
|
|
31
|
+
)
|
|
32
|
+
from .generated.protocol_version import PROTOCOL_DOCUMENT_VERSION, PROTOCOL_VERSION, RUNNER_CHANNEL_ADDRESS
|
|
33
|
+
from .outcomes import Delivery, Err, Handler, Ok, Outcome, RecordedReport
|
|
34
|
+
from .runner import Runner, runner_url
|
|
35
|
+
from .secret_store import FileSecretStore, SecretStore
|
|
36
|
+
|
|
37
|
+
__all__ = [
|
|
38
|
+
"PROTOCOL_DOCUMENT_VERSION",
|
|
39
|
+
"PROTOCOL_VERSION",
|
|
40
|
+
"RUNNER_CHANNEL_ADDRESS",
|
|
41
|
+
"AcceptRefusedError",
|
|
42
|
+
"AnnouncementRejectedError",
|
|
43
|
+
"AuthenticationFailedError",
|
|
44
|
+
"ConnectError",
|
|
45
|
+
"Delivery",
|
|
46
|
+
"DeliveryLostError",
|
|
47
|
+
"Err",
|
|
48
|
+
"FileSecretStore",
|
|
49
|
+
"Handler",
|
|
50
|
+
"MalformedFrameError",
|
|
51
|
+
"MissingSecretError",
|
|
52
|
+
"Ok",
|
|
53
|
+
"Outcome",
|
|
54
|
+
"ProtocolViolationError",
|
|
55
|
+
"RecordedReport",
|
|
56
|
+
"ReportRejectedError",
|
|
57
|
+
"Runner",
|
|
58
|
+
"RunnerCrashedError",
|
|
59
|
+
"SecretStore",
|
|
60
|
+
"SecretStoreError",
|
|
61
|
+
"TronRunnerError",
|
|
62
|
+
"UnreachableError",
|
|
63
|
+
"UnknownHandlerError",
|
|
64
|
+
"__version__",
|
|
65
|
+
"runner_url",
|
|
66
|
+
]
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
"""Decoding and encoding of runner-protocol frames, only through the generated bindings."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from collections.abc import Callable
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from .errors import MalformedFrameError
|
|
10
|
+
from .generated.protocol import (
|
|
11
|
+
AcceptedFrame,
|
|
12
|
+
AcceptFrame,
|
|
13
|
+
AcceptFrameType,
|
|
14
|
+
AcceptRefusedFrame,
|
|
15
|
+
AnnouncedFrame,
|
|
16
|
+
AnnounceFrame,
|
|
17
|
+
AnnounceFrameType,
|
|
18
|
+
AuthenticatedFrame,
|
|
19
|
+
AuthenticateFrame,
|
|
20
|
+
AuthenticateFrameType,
|
|
21
|
+
AuthenticationFailedFrame,
|
|
22
|
+
ProtocolErrorFrame,
|
|
23
|
+
ReportFrame,
|
|
24
|
+
ReportFrameType,
|
|
25
|
+
ReportRecordedFrame,
|
|
26
|
+
ReportRejectedFrame,
|
|
27
|
+
RunnerAnnouncement,
|
|
28
|
+
RunnerProtocolVersion,
|
|
29
|
+
RunOutcome,
|
|
30
|
+
ServerFrameKind,
|
|
31
|
+
ServerFrameTag,
|
|
32
|
+
WorkFrame,
|
|
33
|
+
accept_refused_frame_from_dict,
|
|
34
|
+
accepted_frame_from_dict,
|
|
35
|
+
announced_frame_from_dict,
|
|
36
|
+
authenticated_frame_from_dict,
|
|
37
|
+
authentication_failed_frame_from_dict,
|
|
38
|
+
protocol_error_frame_from_dict,
|
|
39
|
+
report_recorded_frame_from_dict,
|
|
40
|
+
report_rejected_frame_from_dict,
|
|
41
|
+
work_frame_from_dict,
|
|
42
|
+
)
|
|
43
|
+
from .generated.protocol_version import PROTOCOL_VERSION
|
|
44
|
+
from .outcomes import Err, Ok, Outcome
|
|
45
|
+
|
|
46
|
+
ServerFrame = (
|
|
47
|
+
AuthenticatedFrame
|
|
48
|
+
| AnnouncedFrame
|
|
49
|
+
| AuthenticationFailedFrame
|
|
50
|
+
| WorkFrame
|
|
51
|
+
| AcceptedFrame
|
|
52
|
+
| AcceptRefusedFrame
|
|
53
|
+
| ReportRecordedFrame
|
|
54
|
+
| ReportRejectedFrame
|
|
55
|
+
| ProtocolErrorFrame
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
_DECODERS: dict[ServerFrameKind, Callable[[Any], ServerFrame]] = {
|
|
59
|
+
ServerFrameKind.AUTHENTICATED: authenticated_frame_from_dict,
|
|
60
|
+
ServerFrameKind.ANNOUNCED: announced_frame_from_dict,
|
|
61
|
+
ServerFrameKind.AUTHENTICATION_FAILED: authentication_failed_frame_from_dict,
|
|
62
|
+
ServerFrameKind.WORK: work_frame_from_dict,
|
|
63
|
+
ServerFrameKind.ACCEPTED: accepted_frame_from_dict,
|
|
64
|
+
ServerFrameKind.ACCEPT_REFUSED: accept_refused_frame_from_dict,
|
|
65
|
+
ServerFrameKind.REPORT_RECORDED: report_recorded_frame_from_dict,
|
|
66
|
+
ServerFrameKind.REPORT_REJECTED: report_rejected_frame_from_dict,
|
|
67
|
+
ServerFrameKind.PROTOCOL_ERROR: protocol_error_frame_from_dict,
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
# A frame added to the protocol regenerates `ServerFrameKind`; failing here makes that drift loud.
|
|
71
|
+
_UNHANDLED = set(ServerFrameKind) - set(_DECODERS)
|
|
72
|
+
if _UNHANDLED:
|
|
73
|
+
raise RuntimeError(f"protocol {PROTOCOL_VERSION} has server frames this SDK does not decode: {sorted(k.value for k in _UNHANDLED)}")
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def decode_server_frame(text: str) -> ServerFrame:
|
|
77
|
+
try:
|
|
78
|
+
document = json.loads(text)
|
|
79
|
+
kind = ServerFrameTag.from_dict(document).type
|
|
80
|
+
return _DECODERS[kind](document)
|
|
81
|
+
except (ValueError, AssertionError, TypeError, KeyError) as error:
|
|
82
|
+
raise MalformedFrameError(f"not a protocol {PROTOCOL_VERSION} server frame: {error}") from error
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def authenticate_frame(token: str) -> str:
|
|
86
|
+
return json.dumps(AuthenticateFrame(token=token, type=AuthenticateFrameType.AUTHENTICATE).to_dict())
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def announce_frame(
|
|
90
|
+
*,
|
|
91
|
+
handler_keys: list[str],
|
|
92
|
+
concurrency_capacity: int,
|
|
93
|
+
display_name: str | None,
|
|
94
|
+
runner_version: str | None,
|
|
95
|
+
sdk_version: str,
|
|
96
|
+
) -> str:
|
|
97
|
+
announcement = RunnerAnnouncement(
|
|
98
|
+
concurrency_capacity=concurrency_capacity,
|
|
99
|
+
handler_keys=handler_keys,
|
|
100
|
+
display_name=display_name,
|
|
101
|
+
protocol_version=RunnerProtocolVersion(PROTOCOL_VERSION),
|
|
102
|
+
runner_version=runner_version,
|
|
103
|
+
sdk_version=sdk_version,
|
|
104
|
+
)
|
|
105
|
+
return json.dumps(AnnounceFrame(announcement=announcement, type=AnnounceFrameType.ANNOUNCE).to_dict())
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def accept_frame(delivery_id: Any) -> str:
|
|
109
|
+
return json.dumps(AcceptFrame(delivery_id=delivery_id, type=AcceptFrameType.ACCEPT).to_dict())
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def report_frame(delivery_id: Any, secret: str, outcome: Outcome) -> str:
|
|
113
|
+
if isinstance(outcome, Ok):
|
|
114
|
+
wire = RunOutcome(ok=outcome.message)
|
|
115
|
+
elif isinstance(outcome, Err):
|
|
116
|
+
wire = RunOutcome(err=outcome.message)
|
|
117
|
+
else:
|
|
118
|
+
raise TypeError(f"a handler outcome is Ok or Err, not {type(outcome).__name__}")
|
|
119
|
+
return json.dumps(ReportFrame(delivery_id=delivery_id, outcome=wire, secret=secret, type=ReportFrameType.REPORT).to_dict())
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.1.0"
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
"""Typed errors. Every Tron refusal is a value of a generated closed enum, never parsed text."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from uuid import UUID
|
|
6
|
+
|
|
7
|
+
from .generated.protocol import (
|
|
8
|
+
AcceptRefusal,
|
|
9
|
+
ConnectFailure,
|
|
10
|
+
ProtocolViolation,
|
|
11
|
+
ReportRejection,
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class TronRunnerError(Exception):
|
|
16
|
+
"""Base class of every error this package raises or reports."""
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class ConnectError(TronRunnerError):
|
|
20
|
+
"""The runner could not connect; `reason` is the generated `ConnectFailure`."""
|
|
21
|
+
|
|
22
|
+
reason: ConnectFailure
|
|
23
|
+
|
|
24
|
+
def __init__(self, reason: ConnectFailure, detail: str) -> None:
|
|
25
|
+
super().__init__(f"{reason.value}: {detail}")
|
|
26
|
+
self.reason = reason
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class AuthenticationFailedError(ConnectError):
|
|
30
|
+
"""Tron did not accept the worker API key. Not retried."""
|
|
31
|
+
|
|
32
|
+
def __init__(self) -> None:
|
|
33
|
+
super().__init__(ConnectFailure.AUTHENTICATION_FAILED, "the worker API key was not accepted")
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class AnnouncementRejectedError(ConnectError):
|
|
37
|
+
"""Tron refused the announcement (capacity, handler keys, names or versions). Not retried."""
|
|
38
|
+
|
|
39
|
+
violation: ProtocolViolation
|
|
40
|
+
|
|
41
|
+
def __init__(self, violation: ProtocolViolation) -> None:
|
|
42
|
+
super().__init__(ConnectFailure.ANNOUNCEMENT_REJECTED, f"protocol_error {violation.value}")
|
|
43
|
+
self.violation = violation
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class UnreachableError(ConnectError):
|
|
47
|
+
"""The first connection attempt failed at the transport."""
|
|
48
|
+
|
|
49
|
+
def __init__(self, detail: str) -> None:
|
|
50
|
+
super().__init__(ConnectFailure.UNREACHABLE, detail)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class AcceptRefusedError(TronRunnerError):
|
|
54
|
+
"""Tron refused `accept` for a delivery; its handler was not run."""
|
|
55
|
+
|
|
56
|
+
delivery_id: UUID
|
|
57
|
+
reason: AcceptRefusal
|
|
58
|
+
|
|
59
|
+
def __init__(self, delivery_id: UUID, reason: AcceptRefusal) -> None:
|
|
60
|
+
super().__init__(f"accept of delivery {delivery_id} refused: {reason.value}")
|
|
61
|
+
self.delivery_id = delivery_id
|
|
62
|
+
self.reason = reason
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
class ReportRejectedError(TronRunnerError):
|
|
66
|
+
"""Tron rejected a report. It is not retried and the stored secret is kept."""
|
|
67
|
+
|
|
68
|
+
delivery_id: UUID
|
|
69
|
+
reason: ReportRejection
|
|
70
|
+
|
|
71
|
+
def __init__(self, delivery_id: UUID, reason: ReportRejection) -> None:
|
|
72
|
+
super().__init__(f"report of delivery {delivery_id} rejected: {reason.value}")
|
|
73
|
+
self.delivery_id = delivery_id
|
|
74
|
+
self.reason = reason
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
class ProtocolViolationError(TronRunnerError):
|
|
78
|
+
"""Tron answered `protocol_error` on an established connection."""
|
|
79
|
+
|
|
80
|
+
violation: ProtocolViolation
|
|
81
|
+
|
|
82
|
+
def __init__(self, violation: ProtocolViolation) -> None:
|
|
83
|
+
super().__init__(f"protocol_error {violation.value}")
|
|
84
|
+
self.violation = violation
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class MalformedFrameError(TronRunnerError):
|
|
88
|
+
"""Tron sent something that is not a frame of the supported protocol version."""
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
class RunnerCrashedError(TronRunnerError):
|
|
92
|
+
"""The connection supervisor hit an unexpected exception and stopped; the original is `__cause__`."""
|
|
93
|
+
|
|
94
|
+
def __init__(self, cause: Exception) -> None:
|
|
95
|
+
super().__init__(f"the runner stopped on an unexpected {type(cause).__name__}: {cause}")
|
|
96
|
+
self.__cause__ = cause
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
class DeliveryLostError(TronRunnerError):
|
|
100
|
+
"""The connection ended after `accept` was sent and before Tron answered; the delivery is abandoned."""
|
|
101
|
+
|
|
102
|
+
delivery_id: UUID
|
|
103
|
+
|
|
104
|
+
def __init__(self, delivery_id: UUID) -> None:
|
|
105
|
+
super().__init__(f"connection lost before Tron answered the accept of delivery {delivery_id}")
|
|
106
|
+
self.delivery_id = delivery_id
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
class UnknownHandlerError(TronRunnerError):
|
|
110
|
+
"""A delivery arrived for a handler key this runner has not registered, so it was not accepted."""
|
|
111
|
+
|
|
112
|
+
delivery_id: UUID
|
|
113
|
+
handler_key: str
|
|
114
|
+
|
|
115
|
+
def __init__(self, delivery_id: UUID, handler_key: str) -> None:
|
|
116
|
+
super().__init__(f"delivery {delivery_id} is for handler {handler_key!r}, which this runner has not registered")
|
|
117
|
+
self.delivery_id = delivery_id
|
|
118
|
+
self.handler_key = handler_key
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
class SecretStoreError(TronRunnerError):
|
|
122
|
+
"""The secret store failed; the delivery's handler was not run."""
|
|
123
|
+
|
|
124
|
+
delivery_id: UUID
|
|
125
|
+
|
|
126
|
+
def __init__(self, delivery_id: UUID, cause: BaseException) -> None:
|
|
127
|
+
super().__init__(f"secret store failed for delivery {delivery_id}: {cause}")
|
|
128
|
+
self.delivery_id = delivery_id
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
class MissingSecretError(TronRunnerError):
|
|
132
|
+
"""No secret is stored for a delivery that was to be reported."""
|
|
133
|
+
|
|
134
|
+
delivery_id: UUID
|
|
135
|
+
|
|
136
|
+
def __init__(self, delivery_id: UUID) -> None:
|
|
137
|
+
super().__init__(f"no stored secret for delivery {delivery_id}")
|
|
138
|
+
self.delivery_id = delivery_id
|
|
File without changes
|