Skip to main content

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 raises UnreachableError (both are ConnectErrors carrying the generated ConnectFailure reason, 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, optional display_name and runner_version, the SDK version and the protocol version. A refused announcement raises AnnouncementRejectedError.
  • Accepts automatically when work arrives, then persists the one-time delivery secret before running the handler. A refused accept (AcceptRefusedError, with the generated AcceptRefusal reason) means the handler was not run.
  • Reports once with the stored secret. Returning Ok(message) or Err(message) is the report; an exception from the handler is reported as Err. The report may go out on a later connection than the one that accepted. A rejected report raises ReportRejectedError (generated ReportRejection reason) 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)

Source distribution for cruma-tron-runner 0.1.0
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)

Table of built distributions (wheels) for cruma-tron-runner 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page