Web App Integration
Last reviewed: 2026-07-05
Boundary
The Python Server talks to the Anuva Web App through a worker-facing client abstraction under src/anuva_python_server/webapp/. The client can point at the real Web App namespace or the local simulator namespace.
Status: Partial. The Python client and simulator are implemented. The real Web App service is external to this repository. docs/AnuvaWeb_API_Doc.md describes the implemented Web App route contract, but its "File Map" references files from the Web App repository, not files present in this Python Server repository.
Client Operations
| Operation | Status | Python method |
|---|---|---|
| Get next queued job | Implemented | get_next_queued_job(worker_id) |
| List available jobs | Implemented | list_available_jobs(worker_id, filters) |
| Get summary | Implemented | get_job_summary(job_id) |
| Claim job | Implemented | claim_job(job_id, worker_id) |
| Manual claim | Implemented | manual_claim_job(job_id, worker_id) delegates to claim. |
| Get package | Implemented | get_job_package(job_id) |
| Update status | Implemented | update_job_status(job_id, status, progress, message) |
| Heartbeat | Implemented | send_worker_heartbeat(worker_id, payload) |
| Direct upload | Implemented client fallback | upload_render_result(job_id, file_path, metadata) |
| Signed upload create/confirm | Implemented | create_signed_upload(), confirm_signed_upload() |
| Complete/fail/cancel | Implemented | complete_job(), fail_job(), cancel_job() |
Endpoint Defaults
| Operation | Real default | Simulated default |
|---|---|---|
| Next job | /api/worker/v1/jobs/next |
/sim/jobs/available |
| List jobs | /api/worker/v1/jobs/available |
/sim/jobs/available |
| Job summary | /api/worker/v1/jobs/{job_id} |
/sim/jobs/{job_id} |
| Claim | /api/worker/v1/jobs/{job_id}/claim |
/sim/jobs/{job_id}/claim |
| Package | /api/worker/v1/jobs/{job_id}/package |
/sim/jobs/{job_id}/package |
| Status | /api/worker/v1/jobs/{job_id}/status |
/sim/jobs/{job_id}/status |
| Heartbeat | /api/worker/v1/workers/{worker_id}/heartbeat |
/sim/workers/{worker_id}/heartbeat |
| Direct upload | /api/worker/v1/jobs/{job_id}/upload |
/sim/jobs/{job_id}/upload |
| Signed upload | /api/worker/v1/jobs/{job_id}/uploads/signed |
Configured in client, but simulator app does not currently expose it. |
| Confirm upload | /api/worker/v1/jobs/{job_id}/uploads/confirm |
Configured in client, but simulator app does not currently expose it. |
| Complete | /api/worker/v1/jobs/{job_id}/complete |
/sim/jobs/{job_id}/complete |
| Fail | /api/worker/v1/jobs/{job_id}/fail |
/sim/jobs/{job_id}/fail |
| Cancel | /api/worker/v1/jobs/{job_id}/cancel |
/sim/jobs/{job_id}/cancel |
Endpoint paths can be overridden through webapp.endpoints.
Authentication
The real Web App client sends Accept: application/json and, when configured, Authorization: Bearer <token>. The token is loaded from the environment variable named by webapp.api_token_env, default ANUVA_WORKER_API_TOKEN.
Simulator mode does not require a token by default.
Package And Asset Assumptions
RenderJobPackage.config is opaque to the Python Server except for local asset URL rewriting. Assets must have unique assetId values and safe basename filenames. Required asset download/checksum failures abort preparation; optional assets can be skipped unless assets.fail_on_optional_asset_error is true.
When an asset URL has the same origin as the Web App base URL, the downloader can send the worker bearer token for that asset request. It does not send that token to other origins.
Upload Behavior
Real Web App mode prefers signed S3 upload when upload.strategy is signed_s3. Simulator mode uses direct upload because the default upload strategy avoids signed S3 when webapp.mode == simulated.
Known gap: the simulated endpoint map contains signed upload paths, but src/anuva_python_server/simulator/app.py does not expose /sim/jobs/{job_id}/uploads/signed or /sim/jobs/{job_id}/uploads/confirm.
Source Files To Inspect
docs/AnuvaWeb_API_Doc.mddocs/AnuvaPythonServer_SystemDescription.mdsrc/anuva_python_server/webapp/client.pysrc/anuva_python_server/webapp/models.pysrc/anuva_python_server/webapp/uploads.pysrc/anuva_python_server/simulator/app.pytests/unit/test_webapp_models_and_client.py
Current state map: EnvAndServices, KnownGaps.