Skip to main content

Module control_api

tropel_engine

Module control_api 

Source
Expand description

Minimal runtime control API — k6 REST /v1/status parity.

Binds 127.0.0.1:<port> and serves:

  • GET /v1/status → k6 JSON:API shape {"data":{"type":"status","id":"default","attributes":{...}}} (vus / vus-max / paused / running / stopped / tainted)
  • PATCH /v1/status → k6 envelope {"data":{"attributes":{...}}} or a flat {"vus":N,"max":M,"vus-max":N,"paused":bool} — adjusts the externally-controlled scheduler’s VU pool / pause state at runtime. max is clamped to the configured max_vus ceiling, so a client can never grow the pool past the run’s cap. Both max (legacy) and vus-max (k6’s JSON:API field name) are accepted, and the status doc emits BOTH so old and new clients work.
  • POST /v1/stop → stop the run (k6 extension — also achievable via PATCH /v1/status {"stopped":true})
  • PATCH /v1/stop → k6 envelope {"data":{"attributes":{"stopped":true}}} — same as the PATCH /v1/status path, but on the /v1/stop route.
  • GET /v1/metrics → k6 JSON:API envelope of current metric values
  • GET /v1/groups → k6 JSON:API envelope of the group hierarchy
  • GET /v1/setup → the current setup data (or null)
  • PUT /v1/setup → set the setup data from the request body
  • POST /v1/setup → run the script’s setup() and return the result
  • POST /v1/teardown → run the script’s teardown()

Everything else returns 404. This is intentionally dependency-free: a hand-rolled HTTP/1.1 reader keeps the control surface small and avoids pulling a web framework into the engine for one endpoint.

§SUPERSET (k6 v2 divergence)

k6 v2 turns the REST API off by default (GlobalFlags.Address → ""). Tropel serves it whenever a --control-port is configured (for any executor, not just externally-controlled) — a deliberate SUPERSET so integrators (knockport, scripts, or platform operators) can always inspect a live run without reconfiguring the executor type. The HEADER_LINE_LEN / BODY_SIZE caps are the bounds that keep this safe (TR-604).

Structs§

ControlApiState
Shared state for the control API: the scheduler (mutable run state) and read-only handles used by the read-only routes.

Functions§

serve_control_api
Handle the control server task. Runs until the listener errors or the task is aborted by the scenario finishing.