Skip to content

Render Job Lifecycle

Last reviewed: 2026-07-05

State Domains

Domain Source of truth Examples
Web App job state Web App worker API or simulator state queued, claimed, inProgress, uploading, uploadFailed, completed, failed, cancelled
Python local state JobRunner fields and local workspace idle, starting, prepared, rendering, validating_output, uploading, completing
Unity renderer state Unity events and supervisor state ready, rendering, accepted/progress/completed/failed events

Job Status Values

Status: Implemented in src/anuva_python_server/webapp/models.py and mirrored in src/anuva_python_server/simulator/models.py.

Status Meaning
queued Available to claim.
claimed Claimed by a worker but not yet complete.
inProgress Package prepared or Unity rendering is underway.
uploading Rendered output is being uploaded/finalized.
uploadFailed Upload failed after render output was produced.
completed Final media was uploaded and completion was accepted.
failed Worker reported a terminal or operational failure.
cancelled Job was cancelled.

Current Flow

Step Status Implementation
Discover next job Implemented JobRunner.poll_once() calls get_next_queued_job() unless mode is manual.
List jobs for operator Implemented JobRunner.list_available_jobs(), dashboard /api/webapp/jobs/available.
Claim job Implemented claim_job() or manual_claim_job() uses backend claim endpoint.
Enforce one active job Implemented worker.max_active_jobs is limited to 1; manual claim checks active job unless override is set.
Fetch package Implemented prepare_claimed_job() calls get_job_package().
Download assets Implemented download_assets() with retry, checksum validation, optional asset handling.
Rewrite config Implemented write_presentation_configs() writes original and local JSON, replacing matching asset URLs.
Write manifest Implemented write_job_manifest() writes job_manifest.json.
Mark started Implemented Worker sends inProgress, progress 0.0, message job package downloaded.
Wait for local content Implemented run_active_render_job() probes local config and asset URLs before render.start.
Send Unity render command Implemented UnityZmqClient.send_render_start().
Forward progress Implemented render.progress events update Web App inProgress.
Complete render Implemented render.completed triggers MP4 validation, thumbnail generation, upload, and complete.
Fail render Implemented render.failed, timeout, content failure, validation failure, or upload failure report diagnostics.
Cancellation before render Implemented cancel_current_job() cancels local active job without Unity if not rendering.
Cancellation during render Implemented Sends render.cancel, waits for acknowledgement, may stop Unity.
Retry scheduling Planned Retry safety is classified in diagnostics, but there is no retry queue/loop in this repo.

Completion

Completion validates final.mp4 or the outputPath from Unity, checks freshness against render start time, checks minimum size, optionally runs ffprobe, creates a thumbnail artifact, updates job state to uploading, uploads the MP4, calls complete_job(), persists an end health snapshot, and returns to idle.

Upload strategy is configurable:

Strategy Status Notes
signed_s3 Implemented Preferred for real Web App mode; creates signed target, PUTs bytes, retries confirm on network/5xx failures.
payload Implemented fallback Uses direct multipart upload_render_result(). Simulator mode uses direct upload by default.

Failure And Retry Safety

JobRunner.build_failure_report() adds worker id, job id, runner state, retry-safety boolean, last Unity event, log paths, and diagnostics path. Retry safety is currently a classification only.

Retry-safe codes include CONTENT_SERVER_UNAVAILABLE, WEBAPP_UNAVAILABLE, UNITY_NOT_READY, UNITY_START_TIMEOUT, UNITY_PROCESS_EXITED, UNITY_HEARTBEAT_TIMEOUT, UNITY_RENDER_TIMEOUT, and UPLOAD_FAILED.

Terminal codes include JOB_PACKAGE_INVALID, CONFIG_INVALID, OUTPUT_FILE_MISSING, OUTPUT_FILE_INVALID, and JOB_CANCELLED.

Source Files To Inspect

  • src/anuva_python_server/jobs/runner.py
  • src/anuva_python_server/jobs/assets.py
  • src/anuva_python_server/jobs/config_writer.py
  • src/anuva_python_server/jobs/manifest.py
  • src/anuva_python_server/jobs/output.py
  • src/anuva_python_server/webapp/uploads.py
  • tests/unit/test_manual_claim.py
  • tests/unit/test_job_preparation.py
  • tests/unit/test_output_and_completion.py

Operational map: RenderJobFlowMap.