Worker protocol

This is the contract every worker SDK implements. Reference SDKs (eager and lazy modes, no runtime dependencies) exist for Node.js, Python and Java; .NET is the full-featured SDK.

Authentication#

POST /worker/auth_token is anonymous and form-encoded:

grant_type=client_credentials&service_id=<svc>&auth_secret=<secret>&worker_id=<id>

The response matches the client token response. The JWT carries sub (worker id), role = worker and service_id. A 401 means a bad secret or a dead refresh token. Refresh about five minutes before expiry.

Registration#

POST /worker/registration with a bearer token:

{
  "worker_id": "kiwi-worker-1",
  "service_id": "<from the token>",
  "run_mode": "Lazy",
  "methods": ["hello", "longtask"],
  "ip": "192.168.1.20", "port": 55222,
  "version": "1.0.0",
  "tags": { "os": "linux" },
  "supported_executors": ["python", "node"],
  "platform": "linux",
  "interactive_desktop": false,
  "browser_runtime": false
}

run_mode is Lazy, Connected or Eager. ip and port are needed for the lazy-mode probe. The supported_executors, platform, interactive_desktop and browser_runtime fields are for script workers. The response is a string map of application settings (service secrets and script hints) that the worker holds. Register again only when the process starts.

The request loop#

1. Drain. GET /worker/messages returns an array of { request_id, method, lock_required, params } and empties the queue in one atomic read. Eager mode adds ?wait=N so the call hangs until work arrives or about N seconds pass.
2. Lock. If lock_required, call PUT /worker/lock_request/{request_id}. A 2xx means this worker owns it; anything else means another worker has claimed it, so skip.
3. Handle. The worker sees the bare method name (hello), not service/hello. Unknown methods and invalid parameters post an error response.
4. Respond. POST /worker/response with { request_id, status: "success" | "failed" | "error", error_text, result }. On success error_text is null; on failure result is null and error_text is what the client sees.

Lazy-mode wake-up probe#

The worker listens on 0.0.0.0:<wakeup_probe_service_port>. The middleware sends one ASCII JSON packet, for example {"PacketId":"<guid>","Message":{"MessageText":"pull_signal","Parameters":"<request_id or null>"}}. Reply on the same socket with ACK:<PacketId> and drain the queue.

Feedback#

POST /worker/feedback with short keys: rid (request id), st (source type 1 = method request, 2 = background process), sn (source name), ft (feedback type), pr (persist required) and fc (content).

Feedback is fire-and-forget: a failed post must never fail the method.

Heartbeat and shutdown#

GET /worker/heartbeat/{worker_id} every heartbeat_delay (the response is a bare true or false). On SIGINT or SIGTERM send PUT /worker/notify_worker_shutdown/{worker_id}, finish in-flight requests, then exit.

Not yet available in the non-.NET SDKs#

Connected (SignalR) mode, background processes, worker-to-worker invocation and script execution are specified but not part of the Node.js, Python and Java worker SDKs.