cruma-tron-runner
Run Tron jobs on your own machines. Tron pushes work to a connected runner;
the runner accepts it immediately, runs your async handler, and reports Ok(...) or Err(...).
pip install cruma-tron-runner
Python 3.11 or newer. The only dependency is websockets.
import os
from tron_runner import Delivery, FileSecretStore, Ok, Outcome, Runner
runner = Runner(
os.environ["TRON_URL"],
os.environ["TRON_WORKER_KEY"],
secret_store=FileSecretStore(os.environ["TRON_SECRET_DIR"]),
)
async def send_report(delivery: Delivery) -> Outcome:
# Ok marks the run succeeded and Err marks it failed; both carry a message.
return Ok(f"sent the report for {delivery.job_name}")
runner.register("send-report", send_report)
async with runner:
... # keep the process alive; leaving this block finishes in-flight work, reports it, then closes
What the SDK does
- Connects and authenticates with the worker API key. A bad key raises
AuthenticationFailedError; a first attempt that cannot reach Tron raisesUnreachableError(both areConnectErrors carrying the generatedConnectFailurereason, and neither is retried). Once connected, a lost connection is re-established automatically with exponential backoff (100 ms, doubling, capped at 5 s) and a fresh authenticate and announce. - Announces the registered handler keys,
concurrency_capacity, optionaldisplay_nameandrunner_version, the SDK version and the protocol version. A refused announcement raisesAnnouncementRejectedError. - Accepts automatically when work arrives, then persists the one-time delivery secret before running the
handler. A refused accept (
AcceptRefusedError, with the generatedAcceptRefusalreason) means the handler was not run. - Reports once with the stored secret. Returning
Ok(message)orErr(message)is the report; an exception from the handler is reported asErr. The report may go out on a later connection than the one that accepted. A rejected report raisesReportRejectedError(generatedReportRejectionreason) and keeps the stored secret. - Shuts down gracefully:
await runner.stop()takes no new work, waits for in-flight handlers and Tron's answer to their reports, then disconnects.
Errors Tron raises while the runner works in the background are passed to the on_error callback (or logged).
on_connected, on_delivery_accepted and on_report_recorded observe the lifecycle.
Secrets and restarts
The delivery secret is shown once and report must echo it, so it is the only state that survives a restart.
FileSecretStore keeps one 0600 file per delivery in a directory you choose. Implement the SecretStore
protocol (save, load, remove, pending) to keep secrets in a database or secret manager instead.
After a restart, await runner.pending() lists deliveries accepted but not yet reported and
await runner.report_pending(delivery_id, Ok("...")) reports one.
Several handlers per runner
A runner can register any number of handlers. Each work frame names the handler key it was dispatched for, and
the runner runs the handler registered under that key. A delivery for a key with no registered handler is not
accepted and is passed to on_error as UnknownHandlerError (with delivery_id and handler_key).
Multi-handler routing needs a Tron whose work frame carries handler_key.
Protocol messages are generated
tron_runner.generated.protocol is emitted from Tron's published AsyncAPI document by the repository's
npm run generate; nothing in this package hand-writes a frame. tron_runner.PROTOCOL_VERSION is the protocol
version this release speaks. CI fails if the generated files are stale (npm run check:generated) or if the SDK
does not decode every frame the document defines (importing tron_runner checks that against the generated
ServerFrameKind).
MIT licensed.
Metadata
Release files for cruma-tron-runner 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cruma_tron_runner-0.1.0.tar.gz | 25.0 kB | Without provenance | Details for cruma_tron_runner-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cruma_tron_runner-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for cruma_tron_runner-0.1.0-py3-none-any.whl |
Total release size: 49.5 kB
Release files / cruma_tron_runner-0.1.0.tar.gz
| Download URL | cruma_tron_runner-0.1.0.tar.gz |
|---|---|
| Size | 25.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6e117edf40d2e84db51d2fba5387ee94d347cd2bc6c34d94d3b952e17e70fde3
|
|
BLAKE2b-256 checksum How to use checksums |
822a227beb013a688b79ec34643db8a69d97d0a055af0fcfe1cc18d9b477b120
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / cruma_tron_runner-0.1.0-py3-none-any.whl
| Download URL | cruma_tron_runner-0.1.0-py3-none-any.whl |
|---|---|
| Size | 24.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aabbc00c8541cde27b19cd4bad5a21337e281049965b342c5d433ba6bef3bbd4
|
|
BLAKE2b-256 checksum How to use checksums |
2657f9ba98e1157a7c69bd38d3b7e57ea24ad6a0558057956305f62161bf7489
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for cruma-tron-runner 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.