Run Job Contract

Jobs execute bounded server management work.

Implemented Routes

POST /api/v1/run/jobs/claim: claims one queued job for the registered run endpoint.
POST /api/v1/run/jobs/ack: acknowledges an active leased job before execution.
POST /api/v1/run/jobs/progress: reports bounded progress for an active leased job.
POST /api/v1/run/jobs/result: submits a bounded terminal result for an active leased job.
POST /api/v1/run/jobs/cancel: polls platform cancellation requests for active leased jobs.
POST /api/v1/run/jobs/reconcile: reconciles platform-known active jobs after run restart or reconnect.

Payloads

RunJobClaimRequest: session token, run ID, capacity, and supported capabilities.
RunJobClaimResponse: optional job assignment with identity, capability, server instance, logical target key, scoped input ref, idempotency key, lease token, attempt, and polling hint.
RunJobAckRequest: job ID, run ID, session token, lease token, attempt, and bounded message.
RunJobProgressRequest: job ID, run ID, session token, lease token, attempt, percent, sequence, and bounded message.
RunJobResultRequest: job ID, run ID, session token, lease token, attempt, terminal state, progress, bounded message, error code, and result reference.
RunJobCancelPollRequest: run ID, session token, and optional job lease identity.
RunJobReconcileRequest: run ID, session token, and active local job IDs.

Local Journal

Run must keep a local short-term journal for accepted jobs so duplicate delivery, reconnect, and restart can be reconciled.

Lifecycle Executor

The runtime worker executes these bounded lifecycle job capabilities:

process.install
process.start
process.stop

Platform-dispatched config/file jobs are now represented in the run job payload and validated before execution by later worker implementations:

config.write: writes approved config content addressed by a logical config key plus scoped input://... ref.
files.read: reads a declared logical file key and returns results through bounded metadata or artifact refs.
files.write: writes content addressed by a logical file key plus scoped input://... or artifact://... ref.

Plugin-declared remote access jobs use the same job channel and remain bounded metadata envelopes:

remote.ftp.read / remote.ftp.write: platform-mediated FTP file transfer requests.
remote.rsync.read / remote.rsync.write: platform-mediated rsync file transfer requests.
remote.run.files.read / remote.run.files.write: run-mediated logical file operations.
remote.run.process.start / remote.run.process.stop: run-mediated remote process lifecycle operations.
remote.run.db.mysql.query / remote.run.db.sqlite.query: run-mediated database read envelopes with scoped input refs for query payloads.
remote.run.logs.transfer: run-mediated log transfer through log/artifact channels.
remote.run.rcon.command: run-mediated RCON command envelopes with scoped input refs.

Run distribution and runtime support jobs use the same lightweight job lifecycle:

run.self-update: stages an approved run artifact by artifact://... ref, verifies checksum/signature metadata, and reports a rollback-safe status ref.
dependencies.check: runs a plugin-declared typed dependency probe addressed by a logical dependencies/... key.
dependencies.install: runs only an approved typed install plan addressed by dependencies/install/...; arbitrary shell snippets are rejected by validation.
logs.backfill: advances historical log cursors for declared process, file, FTP, SQL, or plugin-specific sources and returns bounded cursor/result refs instead of log bodies.

The executor resolves lifecycle action templates under the scoped server workspace and runs direct command/argument vectors through the process supervisor. It does not run unrestricted shell strings, execute arbitrary plugin code, expose host paths, return raw credentials, open direct sockets, or embed logs/artifacts in job result payloads.

Rules

Job ack must be sent before execution.
Terminal result must be replayable while the journal retains the job.
Large files must be passed as artifact references, not embedded in job payloads.
Config/file job payloads must use logical target keys and scoped input/artifact refs.
Remote database and RCON jobs must use scoped input/artifact refs rather than embedding query or command bodies in job results.
Run self-update, dependency, and log backfill jobs must use declared capabilities, logical target keys, scoped refs, and bounded result refs.
Job payloads must not include logs, artifact chunks, raw host paths, raw credentials, direct sockets, or large inline result bodies.
Process stdout/stderr must be redacted and written to the log spool rather than embedded in progress/result bodies.
Job ack/progress/result/cancel/reconcile calls are lightweight lifecycle metadata and must be able to complete while artifact/file transfer work is active or retrying.
Terminal results must remain idempotent under log and artifact retry pressure and must reference artifacts by safe artifact://... refs rather than embedding transfer payloads.

Deferred Channels

Durable log ingest, artifact chunk transfer, and optional game client bridge traffic remain separate channels and must not be multiplexed through job result payloads. Artifact transfer carries chunk payloads only through /api/v1/run/artifacts/* routes.

5.4 KiB Raw Blame History