Custom workers

Status: proposal; not part of the v0.1 compatibility promise.

Decision

Keep the first release focused on the built-in HTTP worker. A custom-worker contract is a strong next extension because it lets teams use k6, Locust, or domain-specific generators while test-scale continues to own scheduling, pre-scaling, cancellation, history, comparisons, and cost.

Do not expose the current NATS subjects as a public contract. They lack capability negotiation, durable delivery, authentication boundaries, and a stable histogram report format.

Proposed v1 contract

A worker image would implement a small gRPC bidirectional stream:

1. Register advertises protocol version, worker identity, and capabilities.
2. Dispatch contains a run ID, opaque workload payload, target throughput, duration, and deadline.
3. Ready confirms that setup is complete.
4. Start provides a synchronized start time.
5. Progress reports cumulative counters and an HDR histogram snapshot.
6. Cancel requires the worker to stop target traffic within two seconds.
7. Complete reports final counters, histogram, failure reason, and timestamps.

Required properties:

• semantic protocol version and capability negotiation;
• mTLS identity separate from the user API key;
• bounded message and histogram sizes;
• idempotent dispatch and completion by run/worker ID;
• cancellation and heartbeat deadlines;
• conformance tests and a reference SDK;
• no target credentials in logs or persisted failure messages.

Exit criteria

Prototype this only after v0.1 is released. Promote it to stable when a k6 adapter and one non-JavaScript adapter pass cancellation, retry, histogram, and compatibility tests against two consecutive control-plane versions.