Skip to content

docs: scope out the openQA worker protocol - #23

Merged
mimi1vx merged 1 commit into
mainfrom
ad_i_11
Aug 11, 2026
Merged

docs: scope out the openQA worker protocol#23
mimi1vx merged 1 commit into
mainfrom
ad_i_11

Conversation

@mimi1vx

@mimi1vx mimi1vx commented Aug 11, 2026

Copy link
Copy Markdown
Owner

Why

ruoqa is an external REST client. Three routes are reachable only from
inside a running job on an os-autoinst worker:

  • multipart artefact upload (POST /api/v1/jobs/:id/artefact) — the only
    file-upload route in the whole v1 API, and it 404s with No worker assigned unless a worker is currently running the job
  • its chunked-asset variant
  • the X-API-JobToken routes (whoami, mutex, barrier, mm) that
    os-autoinst test modules use to synchronise during a job run
  • the worker WebSocket (/api/v1/ws/:workerid)

Implementing any of this means implementing a worker — a different program
with a different auth model (JOBTOKEN), lifecycle, and wire format, not a
gap in this REST client.

What changed

  • README.md's ## Behaviour section states the exclusion next to the
    existing scope bullets (no typed response models, no CLI binary) and
    names the four excluded surfaces.
  • Documents the escape hatch that already exists for a caller who does hold
    a job token: PreparedRequest's fields are public and Client::execute
    takes one directly, backed by a no_run doctest so it can't silently
    drift.

Documentation-only change — no src/ files touched.

Verification

  • cargo fmt --check
  • cargo clippy --all-targets --locked -- -D warnings
  • cargo test --locked (doctest compiles)
  • cargo check --locked --all-targets
  • cargo deny check

Multipart artefact upload, chunked assets, X-API-JobToken routes, and
the worker WebSocket are only reachable from inside a running job on
an os-autoinst worker — the artefact route even 404s with 'No worker
assigned' outside that context. Implementing any of it means building
a worker: a different program, auth model, and wire format, not a gap
in this REST client.

State the exclusion explicitly next to the existing scope bullets, and
document the escape hatch that already exists for a caller who does
hold a job token: PreparedRequest's fields are public and
Client::execute takes one directly, so nothing is walled off.
@mimi1vx
mimi1vx merged commit 1f90599 into main Aug 11, 2026
5 of 6 checks passed
@mimi1vx
mimi1vx deleted the ad_i_11 branch August 11, 2026 11:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant