Cruma
DashboardDownload

Runner protocol

This chapter is the complete reference for how a runner talks to Tron over a WebSocket. You need it only when you write a runner without one of the Tron runner packages, which already speak the protocol for you.

The protocol described here is version v1, the only version, as served by tron.cruma.io. Tron also publishes it as an AsyncAPI 3.0 document at https://tron.cruma.io/api/asyncapi.json, which needs no sign-in. The frame tables in the message reference at the end of this chapter are generated from that document, so they list exactly what Tron speaks.

Connect and authenticate

Open a WebSocket connection to:

wss://tron.cruma.io/api/runners/ws

The connection carries no credential of its own: send no Authorization header. Authenticate inside the protocol instead:

  1. Create a worker key on the Runners page of Tron. The token is shown once.
  2. Send authenticate with that token as the first frame on the connection.
  3. Tron answers authenticated with a fresh session id, or authentication_failed and then closes the connection. A first frame that is not a valid authenticate, a wrong or revoked token, and a first frame that arrives late all get authentication_failed.

Every frame, in both directions, is one JSON text message: an object whose type field names the frame. Binary messages are not frames. Tron decodes only the frames and fields defined in the message reference: an unknown type, a missing or extra field, or an unknown protocol_version is answered with protocol_error and the reason malformed_message.

The session

A connection that has authenticated is a runner session. From connecting to the final report:

runner                                        Tron
  |  authenticate ------------------------->  |
  |  <---------------------- authenticated    |  or authentication_failed, then close
  |  announce (optional, once) ------------>  |
  |  <------------------------ announced      |
  |            ... wait for work ...          |
  |  <----------------------------- work      |  one delivery of one run
  |  accept ------------------------------->  |  straight away, before accept_deadline
  |  <----------------------- accepted        |  carries the one-time secret
  |            ... run the job ...            |
  |  report, with the secret -------------->  |  one final ok or err result
  |  <------------------- report_recorded     |  or report_rejected
  1. Authenticate, then optionally announce the handler keys and concurrency you support, once.
  2. Wait for work. Waiting can take as long as it takes. A work frame names one delivery and carries no job input or payload: only ids, the job name, the handler key it was dispatched for and two times.
  3. Accept the delivery before its accept_deadline. Tron answers accepted with a secret, or accept_refused and a reason. After a refusal, do not run the job.
  4. Run the job, then report exactly one result with the secret.

Between those steps Tron may also send protocol_error. It answers any frame that breaks the protocol after authentication, names a reason, and leaves the connection open.

Limits and rules

RuleValue
Time to send authenticate after connecting10 seconds by default
Time to accept a deliveryuntil the accept_deadline in work: the push time plus the job's delivery timeout
Final reports per deliveryexactly one
Result message kept by Tron16,384 bytes (16 KiB) by default
announce per connectionat most one

The authentication timeout and the result message limit are Tron configuration. The values above are the defaults; GET https://tron.cruma.io/api/config returns the values a running Tron uses as runner_authentication_timeout_seconds and runner_result_message_limit_bytes, and runner_socket_path gives the WebSocket path.

  • Accept deadline. work carries an accept_deadline: the time Tron pushed the delivery plus the job's delivery timeout. An accept after it is refused with delivery_timed_out, and the delivery counts as failed to deliver.
  • One-time secret. The secret in accepted is shown once, so keep it until you have reported. A report can arrive on a new connection authenticated with the same worker key, for example after the runner restarts.
  • One final report. A delivery takes one report. Its outcome is a single string, either {"ok": "..."} or {"err": "..."}. A second report with a matching secret is rejected with not_in_flight.
  • Result message size. Tron keeps at most the limit above of the outcome's string. A longer string is cut at a character boundary and ends with the text [truncated by Tron], and the report is still recorded.
  • Late. report_recorded carries late, true when the report arrived more than the job's lateness threshold after the run was due. A late report is still recorded.
  • After a disconnect. Depending on the job's retry settings, losing the connection while a delivery is accepted can count as a failed attempt. Otherwise the runner can reconnect with the same worker key and still report with its secret.

Delivery modes and fan-out

The job decides how deliveries of one run relate:

Job's delivery modeWhat the runner sees
one_runnerThe run is pushed to a single session. If another session also tries to accept the same run, it gets accept_refused with the reason already_resolved.
every_connectedEvery connected eligible session receives its own delivery. No accept is refused because another runner accepted: every runner that accepts runs the job and reports it.
advanced_at_least, advanced_at_mostSeveral sessions receive a delivery, each accepted and reported independently. The job's count decides how many successful outcomes make the run succeed.

Legacy and announced sessions

announce is optional. A runner that never announces is a legacy session: it still receives work for every handler key. A runner that announces is an announced session, listed with its handler keys and concurrency capacity, and receives work only for the keys it announced. work carries the handler_key the job was dispatched for, so a runner with several handlers runs the handler with that key.

Example session

One runner's session, frame by frame. The ids are made up. Every frame below is checked against Tron's AsyncAPI document by this book's tests.

The runner authenticates:

{"type":"authenticate","token":"<worker API key token>"}

Tron accepts the token:

{"type":"authenticated","session_id":"5f0c2b8e-4d1a-4c3e-9b7f-2a6d8e1f0c34","worker_api_key_id":"0b7e4c21-93d5-4f6a-8e2b-71c4d9a3f5e0"}

Instead, when the token is wrong or late, Tron sends this and closes the connection:

{"type":"authentication_failed"}

The runner announces its handlers and capacity, once. This step is optional:

{"type":"announce","announcement":{"handler_keys":["backup"],"display_name":null,"runner_version":null,"sdk_version":null,"protocol_version":"v1","concurrency_capacity":1}}

Tron keeps the announcement:

{"type":"announced"}

Instead, when the announcement breaks a constraint:

{"type":"protocol_error","reason":"invalid_announcement"}

Later, Tron pushes a run. The accept_deadline is the push time plus the job's delivery timeout, here 30 seconds:

{"type":"work","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","run_id":"9e4d2a17-b5c8-4f3e-8a61-0d7c2e9b4f15","job_id":"2d8f6b30-7a1e-4c95-b3d4-e5f0a2c81b67","job_name":"nightly-backup","handler_key":"backup","scheduled_for":"2030-01-01T03:00:00.000Z","accept_deadline":"2030-01-01T03:00:32.000Z"}

The runner accepts straight away, before the deadline:

{"type":"accept","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90"}

Tron returns the secret. Store it: it is never shown again. Now run the job:

{"type":"accepted","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","secret":"<one-time delivery secret>"}

Instead, when Tron will not take the accept, do not run the job:

{"type":"accept_refused","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","reason":"delivery_timed_out"}

When the job is done, the runner reports its one final result, on this or on a new connection. An err outcome looks the same with "outcome":{"err":"..."}:

{"type":"report","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","secret":"<one-time delivery secret>","outcome":{"ok":"backed up 42 files"}}

Tron records it and the delivery is finished:

{"type":"report_recorded","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","late":false}

Instead, when Tron could not record the report:

{"type":"report_rejected","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","reason":"wrong_secret"}

Message reference

Versions and compatibility

This reference describes runner protocol v1. A runner states the protocol it speaks in announce.announcement.protocol_version, a RunnerProtocolVersion. This document describes v1, the only version, and Tron decodes only the frames and fields defined here: an unknown frame type, a missing or extra field, or an unknown protocol_version is answered protocol_error with reason malformed_message. Runners that never announce are legacy sessions and stay compatible for this release. A change a v1 runner could not handle (a renamed or removed frame, field or reason value, or a new required field) is published under a new protocol_version, not made to v1, and this document's x-runner-protocol-version names the version it describes.

Frames a runner sends to Tron

authenticate

Must be the first frame on a new connection. Anything else, or no frame in time, is answered with authentication_failed and the connection is closed.

FieldTypeRequiredMeaning
tokenstringyesThe worker API key token shown once when the key was created on the Runners page.

announce

Optional, at most once per connection, after authenticated: declares what this runner can do. Tron answers announced. Runners that never announce are listed as legacy sessions and still receive work.

FieldTypeRequiredMeaning
announcementRunnerAnnouncementyesThe capabilities of this connection.

accept

Takes on a delivery Tron pushed with work. Send it straight away, before the delivery's accept_deadline. Tron answers accepted or accept_refused.

FieldTypeRequiredMeaning
delivery_idstring (uuid)yesThe delivery_id from the work frame.

report

The one final result of an accepted delivery. It may be sent on any connection authenticated with the same worker API key, for example a new one after the runner restarted. Tron answers report_recorded or report_rejected.

FieldTypeRequiredMeaning
delivery_idstring (uuid)yesThe delivery_id from the work frame.
outcomeRunOutcomeyesThe job's result.
secretstringyesThe secret from the accepted frame for this delivery.

Frames Tron sends to a runner

authenticated

Answers a valid authenticate. Several runner processes may authenticate with the same worker API key at once; each connection gets its own session.

FieldTypeRequiredMeaning
session_idstring (uuid)yesNames this one connection.
worker_api_key_idstring (uuid)yesThe worker API key the token belongs to.

announced

Confirms that this connection's announce was retained.

It carries no field besides type.

authentication_failed

The first frame was not a valid authenticate in time: a timeout, a malformed or non-text frame, another frame type, or an unknown, revoked or mismatched token. The connection is closed right after.

It carries no field besides type.

work

A run has been dispatched to this connection as one delivery. It carries no job input or payload: only ids, the job's name, the handler key it was dispatched for and times.

FieldTypeRequiredMeaning
accept_deadlinestring (date-time)yesaccept must arrive by this time. It is the push time plus the job's delivery timeout.
delivery_idstring (uuid)yesNames this delivery; echo it in accept and report.
handler_keyRunnerHandlerKeyyesThe job's runner handler key. For a connection that announced handler keys it is one of them; a connection that never announced receives work for every key. A runner with several handlers runs the one with this key.
job_idstring (uuid)yesThe job that was triggered.
job_namestringyesThe job's name, as the owner set it.
run_idstring (uuid)yesThe run this delivery belongs to.
scheduled_forstring (date-time)yesWhen the run was due.

accepted

Answers a successful accept. Keep the secret: it is shown here once and never again, and report must echo it.

FieldTypeRequiredMeaning
delivery_idstring (uuid)yesThe accepted delivery.
secretstringyesThe one-time secret for this delivery's report.

accept_refused

Answers an accept Tron would not take. Do not run the job.

FieldTypeRequiredMeaning
delivery_idstring (uuid)yesThe refused delivery.
reasonAcceptRefusalyesWhy it was refused.

report_recorded

Answers a report Tron recorded. The delivery is finished.

FieldTypeRequiredMeaning
delivery_idstring (uuid)yesThe reported delivery.
latebooleanyesTrue when the report arrived more than the job's lateness threshold after the run's scheduled_for. A late report is still recorded.

report_rejected

Answers a report Tron could not record.

FieldTypeRequiredMeaning
delivery_idstring (uuid)yesThe delivery named in the report.
reasonReportRejectionyesWhy it was rejected.

protocol_error

An authenticated runner sent a frame the protocol does not allow. The connection stays open.

FieldTypeRequiredMeaning
reasonProtocolViolationyesWhat was wrong.

Types and reasons

The types the frames above refer to. A reason is always one of the listed values; Tron sends no free-text error.

AcceptRefusal

Why accept was refused.

ValueMeaning
unknown_deliveryNo delivery with this id was pushed to this connection's session under an unrevoked worker API key. Accept on the connection that received the work.
delivery_timed_outThe delivery's accept_deadline had passed, including when it had already been marked failed to deliver.
already_resolvedThis same delivery was already accepted (or is in flight) or reported, or its run was cancelled. A cancelled run's delivery stays pushed; the accept is refused because the run is cancelled. For one_runner, another delivery for this run already won the run-scoped accept race. Broadcast modes do not choose a winner.

ProtocolViolation

How an authenticated runner broke the protocol.

ValueMeaning
malformed_messageA frame was not JSON for any runner frame (an unknown type, a missing or extra field, including a handler key that does not match the published handler-key schema), or was a binary frame.
not_authenticatedReserved; not sent today. A first frame other than authenticate is answered with authentication_failed.
already_authenticatedauthenticate was sent again on an authenticated connection.
invalid_announcementThe announcement broke a constraint: zero capacity; no, too many, duplicate, blank or oversized handler keys; a blank or oversized display name or runner version; or a blank, oversized or non-semver SDK version.
already_announcedannounce was sent twice on one connection. Reconnect to replace the announcement.

ReportRejection

Why report was rejected.

ValueMeaning
unknown_deliveryNo delivery with this id belongs to the reporting worker API key, or that key is revoked.
wrong_secretThe secret does not match the one issued in accepted, or the delivery was never accepted, so no secret was issued.
not_in_flightThe secret matched, but the delivery already has its one final report.

RunOutcome

The result a runner reports: exactly one of ok or err, each carrying a single string, so it serializes as {"ok": "..."} or {"err": "..."}.

FieldTypeRequiredMeaning
okstringexactly one of
errstringexactly one of

RunnerAnnouncement

What a runner declares about its connection in announce.

FieldTypeRequiredMeaning
concurrency_capacityinteger (int32)noMaximum concurrent work this session accepts; it must be positive. Omitted values default to 1 for compatibility with older runners.
display_namestring | nullnoOptional human-readable name shown to the owner; a supplied value is non-blank and at most 128 bytes long.
handler_keysRunnerHandlerKey[]yesStable handler keys the runner can execute. The set must contain 1 to 128 unique keys, each 1–128 bytes and matching [A-Za-z0-9][A-Za-z0-9_.-]*.
protocol_versionnull | RunnerProtocolVersionnoTyped version of Tron's runner protocol understood by this session.
runner_versionstring | nullnoOptional runner implementation version, retained as display metadata; a supplied value is non-blank and at most 128 bytes long.
sdk_versionstring | nullnoOptional semantic SDK version, used by the server to report whether this session is older than a peer. A supplied value must parse as a semantic version and be non-blank and at most 128 bytes long.

RunnerHandlerKey

Stable, validated name of a runner handler. Handler keys are durable job configuration, rather than a free-form label inferred from live sessions.

RunnerProtocolVersion

A version of the runner protocol defined by Tron.

ValueMeaning
v1

Back to Runners, or on to runs and their states.